Primary user-facing launch surfaces

fn parse_allow_unix_socket_path(raw: &str) -> Result<AbsolutePathBuf, String>

Purpose: This function turns a user-provided Unix socket path into an absolute path. It is used so the sandbox receives a clear, unambiguous location instead of a path that depends on where the user happened to run the command.

Data flow: It receives a raw text path from the command line. It asks AbsolutePathBuf::relative_to_current_dir to convert that text into an absolute path, using the current directory if the user gave a relative path. If that works, it returns the absolute path; if it fails, it returns a friendly error message that includes the original path.

Call relations: The macOS SeatbeltCommand uses this function as the parser for each --allow-unix-socket value. During command-line parsing, Clap calls this helper to validate and normalize the path before the sandbox runner later uses the resulting allowed socket paths.

Call graph: calls 1 internal fn (relative_to_current_dir).

fn augment_args(cmd: clap::Command) -> clap::Command

Purpose: Adds the normal interactive terminal flags to session commands, but adjusts the prompt argument so it cannot be used in an ambiguous way with --last.

Data flow: It receives a command definition from the argument parser, lets the regular TUI command add its arguments, then changes the prompt argument to conflict with last. It returns the updated command definition.

Call relations: The command-line parser calls this while building the accepted arguments for resume and fork-style session commands. It delegates most of the shape to the normal TUI parser.

Call graph: 1 external calls (augment_args).

fn augment_args_for_update(cmd: clap::Command) -> clap::Command

Purpose: Updates an existing parser definition for session-style TUI flags, again preventing an unclear prompt plus --last combination.

Data flow: It receives an existing command parser, applies the TUI update rules, marks the prompt as conflicting with last, and returns the adjusted parser.

Call relations: The argument parsing library uses this when it needs to update parser state. It mirrors SessionTuiCli::augment_args for parser-update flows.

Call graph: 1 external calls (augment_args_for_update).

fn from_arg_matches(matches: &clap::ArgMatches) -> Result<Self, clap::Error>

Purpose: Turns parsed command-line matches into a SessionTuiCli wrapper around the regular TUI options.

Data flow: It receives parsed argument matches, asks the normal TUI parser to read them, wraps the result, and returns either the wrapper or a parse error.

Call relations: The command-line parser calls this after parsing session commands. It hands the real reading work to the TUI CLI parser.

Call graph: 1 external calls (from_arg_matches).

fn update_from_arg_matches(&mut self, matches: &clap::ArgMatches) -> Result<(), clap::Error>

Purpose: Refreshes an existing SessionTuiCli value from newly parsed command-line matches.

Data flow: It receives parsed matches, passes them into the wrapped TUI options, and updates that inner value in place. It returns success or a parser error.

Call relations: The argument parser calls this in update-style parsing paths. It keeps the wrapper thin and lets the regular TUI CLI own the detailed flag reading.

fn parse_socket_path(raw: &str) -> Result<AbsolutePathBuf, String>

Purpose: Converts a socket path typed by the user into an absolute path that the program can safely use.

Data flow: It receives raw text, resolves it relative to the current directory if needed, and returns either an absolute path object or a readable error message.

Call relations: Command-line options for app-server proxying and stdio-to-socket relay use this as their value parser before later code opens the socket.

Call graph: calls 1 internal fn (relative_to_current_dir).

fn format_exit_messages(exit_info: AppExitInfo, color_enabled: bool) -> Vec<String>

Purpose: Builds the friendly lines shown after the interactive Codex app exits, such as token usage and how to resume the session.

Data flow: It receives exit details and whether colored output is available. It pulls out token usage, a resume hint, and fatal-session information, then returns a list of text lines to print.

Call relations: The exit handler calls this before printing. Several tests call it directly to make sure fatal exits, resume hints, color, and zero-token cases are shown correctly.

Call graph: called by 7 (handle_app_exit, format_exit_messages_applies_color_when_enabled, format_exit_messages_includes_resume_hint_for_fatal_exit, format_exit_messages_includes_resume_hint_without_color, format_exit_messages_includes_session_id_for_fatal_exit_without_resume_hint, format_exit_messages_names_picker_item_when_thread_has_name, format_exit_messages_skips_zero_usage); 3 external calls (new, format!, matches!).

fn handle_app_exit(exit_info: AppExitInfo) -> anyhow::Result<()>

Purpose: Finishes an interactive Codex run by printing errors, usage, resume hints, and possibly starting an update.

Data flow: It receives an AppExitInfo result from the TUI. It prints fatal errors to standard error, prints summary lines to standard output, exits with code 1 for fatal failures, or runs a requested update action.

Call relations: The main dispatcher calls this after interactive, resume, and fork sessions. It uses format_exit_messages for the text and run_update_action if the TUI asked for an update.

Call graph: calls 2 internal fn (format_exit_messages, run_update_action); called by 1 (cli_main); 5 external calls (eprintln!, println!, stdout, exit, on).

fn run_update_action(action: UpdateAction) -> anyhow::Result<()>

Purpose: Runs the platform-specific command that updates Codex and reports whether it worked.

Data flow: It receives an update action, turns it into a command and arguments, normalizes paths for Windows Subsystem for Linux when needed, runs the process, and returns success or an error if the command failed.

Call relations: It is called after an interactive exit requests an update and by the explicit codex update command. It hands off to the operating system process launcher.

Call graph: calls 3 internal fn (normalize_for_wsl, command_args, command_str); called by 2 (handle_app_exit, run_update_command); 3 external calls (bail!, new, println!).

fn run_update_command() -> anyhow::Result<()>

Purpose: Implements codex update by choosing the right update action for the current installation.

Data flow: It checks whether this is a debug build, refuses updates there, otherwise asks the TUI update helper how Codex was installed. If an update method is found, it runs it; otherwise it returns guidance to update manually.

Call relations: The main command dispatcher calls this for the Update subcommand. It delegates the actual command execution to run_update_action.

Call graph: calls 1 internal fn (run_update_action); called by 1 (cli_main); 2 external calls (bail!, get_update_action).

fn run_execpolicycheck(cmd: ExecPolicyCheckCommand) -> anyhow::Result<()>

Purpose: Runs the hidden exec-policy checker command.

Data flow: It receives the already parsed policy-check command and calls its run method. The result is passed back as success or failure.

Call relations: The main dispatcher calls it for codex execpolicy check, keeping that branch small.

Call graph: calls 1 internal fn (run); called by 1 (cli_main).

async fn run_session_archive_cli_command(
    action: codex_tui::SessionArchiveAction,
    cmd: SessionArchiveCommand,
    mut interactive: TuiCli,
    root_config_overrides: CliConfigOverrides,
    r

Purpose: Runs archive, unarchive, or delete actions for saved interactive sessions.

Data flow: It receives the desired archive action, the session target, TUI options, root config overrides, remote settings, and executable paths. It merges options, resolves any remote endpoint, calls the TUI session archive command, and returns the command’s output text.

Call relations: The main dispatcher uses this for archive, delete, and unarchive. It prepares inputs with finalize_session_archive_interactive and resolve_remote_endpoint before handing off to codex_tui.

Call graph: calls 2 internal fn (finalize_session_archive_interactive, resolve_remote_endpoint); called by 1 (cli_main); 1 external calls (run_session_archive_command).

fn delete_action(target: &str, force: bool) -> anyhow::Result<codex_tui::SessionArchiveAction>

Purpose: Builds the correct delete behavior, including whether the user must confirm deletion.

Data flow: It receives a target string and a force flag. If forced deletion is requested, it verifies the target is a session UUID; then it returns a delete action that either skips or requires confirmation.

Call relations: The delete branch of the dispatcher calls this before running the shared session archive command. A test also checks the UUID safety rule.

Call graph: calls 1 internal fn (from_string); called by 2 (cli_main, delete_force_requires_uuid); 2 external calls (bail!, Delete).

async fn run_debug_app_server_command(cmd: DebugAppServerCommand) -> anyhow::Result<()>

Purpose: Runs app-server debugging tools, currently sending a test message through the app-server V2 path.

Data flow: It receives the parsed debug app-server command, finds the current Codex executable, and sends the requested user message through the test client. It returns whatever success or error the client reports.

Call relations: The main dispatcher calls this for codex debug app-server. It hands the actual protocol test to codex_app_server_test_client.

Call graph: called by 1 (cli_main); 2 external calls (send_message_v2, current_exe).

fn to_overrides(&self) -> anyhow::Result<Vec<String>>

Purpose: Turns --enable and --disable feature flags into normal config override strings.

Data flow: It reads the feature names stored in the CLI struct, validates each name, and produces strings like features.some_feature=true or features.some_feature=false.

Call relations: The main dispatcher calls this early so feature toggles flow through the same path as other command-line config overrides. It relies on FeatureToggles::validate_feature.

Call graph: 3 external calls (validate_feature, new, format!).

fn validate_feature(feature: &str) -> anyhow::Result<()>

Purpose: Rejects feature flag names that Codex does not recognize.

Data flow: It receives a feature key, checks it against the known feature list, and returns success or an error naming the unknown flag.

Call relations: Feature override conversion and feature config editing call this before accepting user input.

Call graph: called by 2 (disable_feature_in_config, enable_feature_in_config); 2 external calls (bail!, is_known_feature_key).

fn stage_str(stage: Stage) -> &'static str

Purpose: Converts a feature’s development stage into plain text for display.

Data flow: It receives a feature stage enum and returns a short label such as experimental, stable, or removed.

Call relations: The features list branch of the main dispatcher uses it when printing the feature table.

Call graph: called by 1 (cli_main).

fn main() -> anyhow::Result<()>

Purpose: Starts the Codex CLI process.

Data flow: It reads a remote-control environment setting, then enters the special arg0 dispatcher, which can route alternate executable names before running cli_main.

Call relations: This is the process entrypoint. It hands the real command handling to cli_main through arg0_dispatch_or_else.

Call graph: 2 external calls (take_remote_control_disabled_env, arg0_dispatch_or_else).

async fn cli_main(
    arg0_paths: Arg0DispatchPaths,
    remote_control_disabled: bool,
) -> anyhow::Result<()>

Purpose: This is the central traffic controller for every codex command.

Data flow: It parses the command line, merges feature toggles and config overrides, checks whether root flags are allowed, then matches the selected subcommand. Each branch prepares that command’s settings and calls the crate or helper that performs the real work.

Call relations: It is called by main after arg0 setup. It calls most helper functions in this file and many subsystem entrypoints, including the TUI, exec runner, app server, login, sandbox, debug tools, and feature editing.

Call graph: calls 45 internal fn (run_apply_command, run_app, delete_action, disable_feature_in_config, run_doctor, enable_feature_in_config, finalize_fork_interactive, finalize_resume_interactive, handle_app_exit, loader_overrides_for_profile (+15 more)); 28 external calls (default, try_parse_from, with_capacity, bail!, clone, parse, Review, app_server_control_socket_path, run_main_with_transport_options, bootstrap (+15 more)).

fn profile_v2_for_subcommand(
    interactive: &'a TuiCli,
    subcommand: &Subcommand,
) -> anyhow::Result<Option<&'a ProfileV2Name>>

Purpose: Decides whether the --profile config shortcut is allowed for the chosen subcommand.

Data flow: It reads the profile selected on the interactive options and the chosen subcommand. Runtime-style commands are allowed to use it; configuration or tooling commands get a clear error.

Call relations: The main dispatcher calls this after parsing. Tests call it through a small helper to verify which commands may use profiles.

Call graph: called by 2 (cli_main, profile_v2_for_args); 1 external calls (bail!).

async fn run_exec_server_command(
    cmd: ExecServerCommand,
    arg0_paths: &Arg0DispatchPaths,
    root_config_overrides: &CliConfigOverrides,
    strict_config: bool,
) -> anyhow::Result<()>

Purpose: Starts the standalone exec-server either locally or as a registered remote environment.

Data flow: It receives exec-server CLI settings, executable paths, config overrides, and strict-config choice. It builds runtime paths, optionally loads config and authentication, then either registers with a remote service or starts a local listener.

Call relations: The main dispatcher calls it for codex exec-server. It calls config and authentication helpers before handing off to codex_exec_server.

Call graph: calls 4 internal fn (load_exec_server_config, load_exec_server_remote_auth_provider, new, new); called by 1 (cli_main); 2 external calls (run_main, run_remote_environment).

async fn load_exec_server_remote_auth_provider(
    config: &codex_core::config::Config,
    base_url: &str,
    use_agent_identity_auth: bool,
) -> anyhow::Result<codex_api::SharedAuthProvider>

Purpose: Prepares the authentication provider used when registering an exec-server with a remote service.

Data flow: It receives loaded config, the remote URL, and whether to use Agent Identity auth. It reads the appropriate credentials, verifies the auth type is allowed, applies API-key host safety checks, and returns a shared auth provider.

Call relations: Remote exec-server startup calls this after loading config. It may call load_exec_server_remote_auth, is_supported_exec_server_remote_auth, and validate_api_key_remote_host.

Call graph: calls 4 internal fn (is_supported_exec_server_remote_auth, load_exec_server_remote_auth, validate_api_key_remote_host, from_agent_identity_jwt); called by 1 (run_exec_server_command); 3 external calls (bail!, read_codex_access_token_from_env, auth_provider_from_auth).

fn is_supported_exec_server_remote_auth(auth: &CodexAuth) -> bool

Purpose: Checks whether a stored login method is allowed for remote exec-server registration.

Data flow: It receives a Codex auth object and returns true only for ChatGPT auth or API-key auth.

Call relations: The remote auth provider builder calls this before accepting stored credentials.

Call graph: calls 2 internal fn (is_api_key_auth, is_chatgpt_auth); called by 1 (load_exec_server_remote_auth_provider).

fn validate_api_key_remote_host(base_url: &str) -> anyhow::Result<()>

Purpose: Prevents API keys from being sent to unsafe remote exec-server registration URLs.

Data flow: It parses the base URL, checks its host and scheme, and allows only HTTPS OpenAI domains or loopback addresses, with plain HTTP allowed only for loopback. Otherwise it returns an error.

Call relations: Remote exec-server auth setup calls this when API-key auth is used. Several tests call it directly to verify allowed and rejected hosts.

Call graph: called by 3 (load_exec_server_remote_auth_provider, exec_server_remote_api_key_auth_rejects_http_openai_domain, exec_server_remote_api_key_auth_rejects_suffix_spoof); 2 external calls (bail!, parse).

async fn load_exec_server_config(
    root_config_overrides: &CliConfigOverrides,
    strict_config: bool,
) -> anyhow::Result<codex_core::config::Config>

Purpose: Loads Codex configuration for exec-server startup.

Data flow: It receives root CLI config overrides and a strict-config flag, parses overrides, builds the config, and returns the loaded configuration or an error.

Call relations: Exec-server startup calls this before remote registration and also to validate config for strict local startup.

Call graph: calls 1 internal fn (parse_overrides); called by 1 (run_exec_server_command); 1 external calls (default).

async fn load_exec_server_remote_auth(
    config: &codex_core::config::Config,
    missing_auth_error: &'static str,
) -> anyhow::Result<codex_login::CodexAuth>

Purpose: Loads the user’s stored auth for remote exec-server registration, retrying once after a reload.

Data flow: It receives config and an error message to use if no auth exists. It creates an auth manager, asks for auth, reloads if needed, and returns the auth or the supplied missing-auth error.

Call relations: The remote auth provider helper calls this for normal ChatGPT or API-key authentication.

Call graph: calls 1 internal fn (shared_from_config); called by 1 (load_exec_server_remote_auth_provider).

async fn enable_feature_in_config(feature: &str) -> anyhow::Result<()>

Purpose: Turns on a named feature flag in the user’s config file.

Data flow: It validates the feature name, finds the Codex home directory, edits config.toml to set the feature to true, prints confirmation, and may warn if the feature is still under development.

Call relations: The main dispatcher calls it for codex features enable. It uses FeatureToggles::validate_feature and maybe_print_under_development_feature_warning.

Call graph: calls 4 internal fn (validate_feature, maybe_print_under_development_feature_warning, new, find_codex_home); called by 1 (cli_main); 1 external calls (println!).

async fn disable_feature_in_config(feature: &str) -> anyhow::Result<()>

Purpose: Turns off a named feature flag in the user’s config file.

Data flow: It validates the feature name, finds Codex home, edits config.toml to set the feature to false, and prints confirmation.

Call relations: The main dispatcher calls it for codex features disable.

Call graph: calls 3 internal fn (validate_feature, new, find_codex_home); called by 1 (cli_main); 1 external calls (println!).

fn loader_overrides_for_profile(
    profile_v2: Option<&ProfileV2Name>,
) -> anyhow::Result<LoaderOverrides>

Purpose: Builds config loader settings for an optional named profile.

Data flow: It receives an optional profile name. If present, it finds Codex home and points the config loader at that profile’s config file; otherwise it returns default loader settings.

Call relations: Runtime commands and prompt-input debugging call this when they need profile-specific config loading.

Call graph: calls 2 internal fn (find_codex_home, resolve_profile_v2_config_path); called by 2 (cli_main, run_debug_prompt_input_command); 2 external calls (default, default).

fn maybe_print_under_development_feature_warning(codex_home: &std::path::Path, feature: &str)

Purpose: Warns the user when they enable a feature that is explicitly marked incomplete.

Data flow: It receives Codex home and a feature name, looks up that feature, and if its stage is under development prints a warning with the config path for suppressing the warning.

Call relations: Feature enabling calls this after writing the config change.

Call graph: called by 1 (enable_feature_in_config); 3 external calls (join, eprintln!, matches!).

async fn run_debug_trace_reduce_command(cmd: DebugTraceReduceCommand) -> anyhow::Result<()>

Purpose: Replays a rollout trace bundle and writes a smaller state JSON file for inspection.

Data flow: It receives a trace bundle path and optional output path, replays the bundle, serializes the reduced state as pretty JSON, writes it to disk, and prints the output path.

Call relations: The main dispatcher calls it for the hidden debug trace-reduce tool.

Call graph: called by 1 (cli_main); 4 external calls (replay_bundle, println!, to_vec_pretty, write).

async fn run_debug_prompt_input_command(
    cmd: DebugPromptInputCommand,
    root_config_overrides: CliConfigOverrides,
    interactive: TuiCli,
    arg0_paths: Arg0DispatchPaths,
) -> anyhow::Resul

Purpose: Shows exactly what prompt input Codex would send to the model after applying config, images, and user instructions.

Data flow: It receives prompt debug arguments, root overrides, interactive CLI settings, and executable paths. It builds config, converts images and prompt text into user input items, builds the final prompt input, and prints it as JSON.

Call relations: The main dispatcher calls it for codex debug prompt-input. It uses profile loading, config building, and codex_core::build_prompt_input.

Call graph: calls 3 internal fn (loader_overrides_for_profile, new, parse_overrides); called by 1 (cli_main); 7 external calls (new, default, new, build_prompt_input, default, println!, String).

async fn run_debug_models_command(
    cmd: DebugModelsCommand,
    root_config_overrides: CliConfigOverrides,
) -> anyhow::Result<()>

Purpose: Prints the raw model catalog that Codex knows about.

Data flow: It receives the debug models command and config overrides. It either loads the bundled catalog or builds config and auth to fetch or read the online model catalog, then writes JSON to standard output.

Call relations: The main dispatcher calls it for codex debug models.

Call graph: calls 2 internal fn (shared_from_config, parse_overrides); called by 1 (cli_main); 6 external calls (build_models_manager, bundled_models_response, default, println!, to_writer, stdout).

async fn run_debug_clear_memories_command(
    root_config_overrides: &CliConfigOverrides,
) -> anyhow::Result<()>

Purpose: Clears local memory data for a fresh debugging start.

Data flow: It receives config overrides, builds config, clears memory rows in the SQLite state area, clears memory directories under Codex home, and prints what was cleared.

Call relations: The main dispatcher calls it for the hidden debug clear-memories command.

Call graph: calls 2 internal fn (clear_memory_data_in_sqlite_home, parse_overrides); called by 1 (cli_main); 5 external calls (clear_memory_roots_contents, memories_db_path, default, format!, println!).

fn prepend_config_flags(
    subcommand_config_overrides: &mut CliConfigOverrides,
    cli_config_overrides: CliConfigOverrides,
)

Purpose: Merges root-level -c key=value config overrides into a subcommand’s overrides with lower priority.

Data flow: It receives mutable subcommand overrides and root overrides, then prepends the root values so later subcommand-specific values can win.

Call relations: The main dispatcher and session finalizers use it whenever both root and subcommand config flags may exist.

Call graph: calls 1 internal fn (prepend_root_overrides); called by 4 (cli_main, finalize_fork_interactive, finalize_resume_interactive, finalize_session_archive_interactive).

fn reject_remote_mode_for_subcommand(
    remote: Option<&str>,
    remote_auth_token_env: Option<&str>,
    subcommand: &str,
) -> anyhow::Result<()>

Purpose: Stops users from using interactive remote-TUI options with commands that do not support them.

Data flow: It receives optional remote address, optional auth-token environment variable name, and a subcommand name. If either remote option is present, it returns a clear error; otherwise it succeeds.

Call relations: Most non-interactive branches in cli_main call this before running. App-server-specific rejection also delegates to it, and tests verify the messages.

Call graph: called by 5 (cli_main, reject_remote_mode_for_app_server_subcommand, reject_remote_auth_token_env_for_non_interactive_subcommands, reject_remote_flag_for_remote_control, reject_remote_mode_for_non_interactive_subcommands); 1 external calls (bail!).

fn reject_root_strict_config_for_subcommand(
    strict_config: bool,
    subcommand: &Option<Subcommand>,
) -> anyhow::Result<()>

Purpose: Rejects root-level --strict-config for subcommands that cannot honor it safely.

Data flow: It receives the root strict flag and selected subcommand. If strict mode is off, it succeeds; otherwise it finds whether the subcommand is unsupported and returns an error if needed.

Call relations: The main dispatcher calls it after parsing. Tests call it directly for supported and unsupported cases.

Call graph: calls 2 internal fn (reject_strict_config_for_unsupported_subcommand, unsupported_subcommand_name_for_strict_config); called by 3 (cli_main, root_strict_config_is_rejected_for_unsupported_subcommands, root_strict_config_is_supported_for_exec_server).

fn unsupported_subcommand_name_for_strict_config(
    subcommand: &Option<Subcommand>,
) -> Option<&'static str>

Purpose: Maps a selected subcommand to the user-facing name to mention when root --strict-config is not allowed.

Data flow: It receives the optional subcommand and returns either no name, meaning strict config is allowed, or a static command-name string for the rejection message.

Call relations: The strict-config rejection helper calls this. It uses app_server_subcommand_name for nested app-server tools.

Call graph: calls 1 internal fn (app_server_subcommand_name); called by 1 (reject_root_strict_config_for_subcommand).

fn reject_strict_config_for_app_server_subcommand(
    strict_config: bool,
    subcommand: Option<&AppServerSubcommand>,
) -> anyhow::Result<()>

Purpose: Rejects --strict-config for app-server tooling subcommands while allowing it for normal app-server startup.

Data flow: It receives the strict flag and optional app-server subcommand. If no nested subcommand exists it succeeds; otherwise it builds the nested name and rejects strict mode when set.

Call relations: The app-server branch in cli_main calls this, and tests verify proxy/tooling rejection.

Call graph: calls 2 internal fn (app_server_subcommand_name, reject_strict_config_for_unsupported_subcommand); called by 2 (cli_main, app_server_subcommands_reject_strict_config).

fn reject_strict_config_for_unsupported_subcommand(
    strict_config: bool,
    subcommand: &str,
) -> anyhow::Result<()>

Purpose: Produces the shared error for a command that does not support --strict-config.

Data flow: It receives a strict flag and subcommand name. If strict mode is true, it returns an error naming the command; otherwise it succeeds.

Call relations: Root strict-config checks and app-server strict checks both call this.

Call graph: called by 2 (reject_root_strict_config_for_subcommand, reject_strict_config_for_app_server_subcommand); 1 external calls (bail!).

fn reject_remote_mode_for_app_server_subcommand(
    remote: Option<&str>,
    remote_auth_token_env: Option<&str>,
    subcommand: Option<&AppServerSubcommand>,
) -> anyhow::Result<()>

Purpose: Applies the remote-mode rejection rule to app-server subcommands with clear nested command names.

Data flow: It receives remote options and an optional app-server subcommand, converts the subcommand into a display name, and delegates to the generic remote rejection helper.

Call relations: The app-server branch of cli_main calls this before running app-server tooling. Tests call it for proxy, version, and schema-generation cases.

Call graph: calls 2 internal fn (app_server_subcommand_name, reject_remote_mode_for_subcommand); called by 4 (cli_main, reject_remote_auth_token_env_for_app_server_generate_internal_json_schema, reject_remote_auth_token_env_for_app_server_proxy, reject_remote_auth_token_env_for_app_server_version).

fn app_server_subcommand_name(subcommand: Option<&AppServerSubcommand>) -> &'static str

Purpose: Turns a nested app-server command into the exact text users recognize from the CLI.

Data flow: It receives an optional app-server subcommand and returns a static string such as app-server daemon start or app-server proxy.

Call relations: Strict-config and remote-mode rejection helpers call this to produce precise error messages.

Call graph: called by 3 (reject_remote_mode_for_app_server_subcommand, reject_strict_config_for_app_server_subcommand, unsupported_subcommand_name_for_strict_config).

async fn print_app_server_daemon_output(command: AppServerLifecycleCommand) -> anyhow::Result<()>

Purpose: Runs an app-server daemon lifecycle command and prints its JSON result.

Data flow: It receives a lifecycle command such as start, stop, restart, or version, awaits the daemon response, serializes it to JSON, and prints it.

Call relations: The app-server daemon branch of cli_main calls this for most daemon actions.

Call graph: called by 1 (cli_main); 2 external calls (run, println!).

async fn print_app_server_remote_control_output(
    mode: AppServerRemoteControlMode,
) -> anyhow::Result<()>

Purpose: Changes the app-server daemon’s remote-control setting and prints the JSON result.

Data flow: It receives the desired remote-control mode, asks the daemon layer to set it, serializes the response, and prints it.

Call relations: The app-server daemon branch calls it for enable-remote-control and disable-remote-control.

Call graph: called by 1 (cli_main); 2 external calls (set_remote_control, println!).

fn read_remote_auth_token_from_env_var_with(
    env_var_name: &str,
    get_var: F,
) -> anyhow::Result<String>

Purpose: Reads a bearer token from an environment variable, with a test-friendly way to supply the environment lookup.

Data flow: It receives an environment variable name and a lookup function. It reads the value, trims whitespace, rejects missing or empty values, and returns the token string.

Call relations: The normal environment reader wraps this. Tests call it with fake lookup functions to check missing, trimmed, and empty cases.

Call graph: called by 4 (read_remote_auth_token_from_env_var, read_remote_auth_token_from_env_var_rejects_empty_values, read_remote_auth_token_from_env_var_reports_missing_values, read_remote_auth_token_from_env_var_trims_values); 1 external calls (bail!).

fn read_remote_auth_token_from_env_var(env_var_name: &str) -> anyhow::Result<String>

Purpose: Reads a remote app-server authentication token from the real process environment.

Data flow: It receives an environment variable name and returns the trimmed token or an error if the variable is missing or empty.

Call relations: Remote endpoint resolution calls this when the user supplied --remote-auth-token-env.

Call graph: calls 1 internal fn (read_remote_auth_token_from_env_var_with); called by 1 (resolve_remote_endpoint).

async fn run_interactive_tui(
    mut interactive: TuiCli,
    remote: Option<String>,
    remote_auth_token_env: Option<String>,
    arg0_paths: Arg0DispatchPaths,
) -> std::io::Result<AppExitInfo>

Purpose: Starts the interactive terminal UI, with safety checks and local database recovery guidance.

Data flow: It receives TUI options, optional remote connection settings, and executable paths. It normalizes prompt line endings, checks terminal support, resolves remote auth, starts the TUI, and if startup fails due to a damaged local database it may back up files and retry.

Call relations: The main dispatcher calls this for plain codex, resume, and fork. It uses confirm, resolve_remote_endpoint, and local state recovery helpers before calling codex_tui::run_main.

Call graph: calls 4 internal fn (confirm, is_remote_auth_usage_error, resolve_remote_endpoint, fatal); called by 1 (cli_main); 14 external calls (new, terminal_info, eprintln!, format!, backup_files_for_fresh_start, confirm_fresh_start_rebuild, is_auto_backup_recoverable, is_locked, print_auto_backup_start, print_diagnostic_guidance (+4 more)).

fn resolve_remote_endpoint(
    remote: Option<String>,
    remote_auth_token_env: Option<String>,
) -> std::io::Result<Option<codex_tui::RemoteAppServerEndpoint>>

Purpose: Turns remote TUI flags into a concrete remote app-server endpoint, including optional auth.

Data flow: It receives an optional remote address and optional token environment variable name. It parses the address, checks whether token auth is allowed for that address, reads the token if requested, attaches it, and returns the endpoint or an I/O-style error.

Call relations: Interactive TUI startup and session archive commands call this before connecting to a remote app server.

Call graph: calls 1 internal fn (read_remote_auth_token_from_env_var); called by 2 (run_interactive_tui, run_session_archive_cli_command); 2 external calls (other, remote_addr_supports_auth_token).

fn is_remote_auth_usage_error(err: &std::io::Error) -> bool

Purpose: Recognizes remote-auth errors that should be shown as friendly fatal app messages instead of raw I/O failures.

Data flow: It receives an I/O error, converts it to text, and checks whether it starts with the known --remote-auth-token-env usage message.

Call relations: Interactive TUI startup calls this when remote endpoint resolution fails.

Call graph: called by 1 (run_interactive_tui); 1 external calls (to_string).

fn confirm(prompt: &str) -> std::io::Result<bool>

Purpose: Asks the user a yes-or-no question in the terminal.

Data flow: It prints a prompt to standard error, reads one line from standard input, trims it, and returns true only for y or yes.

Call relations: Interactive startup uses this when TERM=dumb but a real terminal is available, asking whether to continue anyway.

Call graph: called by 1 (run_interactive_tui); 3 external calls (new, eprintln!, stdin).

fn finalize_resume_interactive(
    mut interactive: TuiCli,
    root_config_overrides: CliConfigOverrides,
    session_id: Option<String>,
    last: bool,
    show_all: bool,
    include_non_interact

Purpose: Builds the final TUI settings for codex resume.

Data flow: It receives root interactive settings, root config overrides, resume selection flags, and resume-scoped TUI flags. It decides whether to show a picker, use the last session, or use a specific session, merges flags, prepends root config overrides, and returns the final TUI config.

Call relations: The main dispatcher calls this before starting the TUI for resume. Tests use a helper that parses arguments and calls it directly.

Call graph: calls 2 internal fn (merge_interactive_cli_flags, prepend_config_flags); called by 2 (cli_main, finalize_resume_from_args).

fn finalize_fork_interactive(
    mut interactive: TuiCli,
    root_config_overrides: CliConfigOverrides,
    session_id: Option<String>,
    last: bool,
    show_all: bool,
    mut fork_cli: TuiCli,

Purpose: Builds the final TUI settings for codex fork.

Data flow: It receives root interactive settings, root overrides, fork selection flags, and fork-scoped TUI flags. It decides picker/last/session behavior, merges subcommand flags, prepends root config, and returns the final TUI config.

Call relations: The main dispatcher calls this before starting the TUI for fork. Tests call it through a parsing helper.

Call graph: calls 2 internal fn (merge_interactive_cli_flags, prepend_config_flags); called by 2 (cli_main, finalize_fork_from_args).

fn finalize_session_archive_interactive(
    mut interactive: TuiCli,
    root_config_overrides: CliConfigOverrides,
    archive_cli: SessionArchiveConfigOverrides,
) -> TuiCli

Purpose: Builds the TUI-style configuration used by archive, unarchive, and delete session commands.

Data flow: It receives root interactive settings, root config overrides, and archive-scoped options. It applies shared command overrides, strict config, and raw config overrides, then prepends root overrides and returns the result.

Call relations: The shared session archive runner calls this. Tests call it through an archive parsing helper.

Call graph: calls 1 internal fn (prepend_config_flags); called by 2 (run_session_archive_cli_command, finalize_archive_from_args).

fn merge_interactive_cli_flags(interactive: &mut TuiCli, subcommand_cli: TuiCli)

Purpose: Applies subcommand-scoped TUI flags on top of root TUI flags.

Data flow: It receives mutable root interactive settings and a subcommand TUI settings value. It applies only explicitly meaningful subcommand choices, normalizes prompt line endings, and appends subcommand config overrides with higher priority.

Call relations: Resume and fork finalizers call this so their own flags win over root-level defaults.

Call graph: called by 2 (finalize_fork_interactive, finalize_resume_interactive).

fn print_completion(cmd: CompletionCommand)

Purpose: Generates shell completion script text for the requested shell.

Data flow: It receives the completion command, builds the full Codex command definition, and writes the generated completion script to standard output.

Call relations: The main dispatcher calls it for codex completion.

Call graph: called by 1 (cli_main); 3 external calls (generate, command, stdout).

fn exec_server_remote_auth_accepts_api_key_auth()

Purpose: Checks that API-key authentication is considered valid for remote exec-server registration.

Data flow: It creates a fake API-key auth object, passes it to the support check, and asserts the result is true.

Call relations: This test protects the behavior used by load_exec_server_remote_auth_provider.

Call graph: calls 1 internal fn (from_api_key); 1 external calls (assert!).

fn exec_server_remote_api_key_auth_accepts_https_openai_domains()

Purpose: Checks that API-key remote registration allows secure OpenAI-owned domains.

Data flow: It loops over HTTPS OpenAI domain examples and asserts host validation succeeds.

Call relations: This test covers the allow-list logic in validate_api_key_remote_host.

Call graph: 1 external calls (assert!).

fn exec_server_remote_api_key_auth_accepts_http_loopback()

Purpose: Checks that local loopback HTTP URLs are allowed for API-key registration.

Data flow: It tries localhost, IPv4 loopback, and IPv6 loopback URLs and expects validation success.

Call relations: This test covers local-development exceptions in validate_api_key_remote_host.

Call graph: 1 external calls (assert!).

fn exec_server_remote_api_key_auth_rejects_http_openai_domain()

Purpose: Checks that OpenAI domains still require HTTPS when API keys are involved.

Data flow: It passes plain HTTP OpenAI URLs to the validator and asserts the exact rejection message.

Call relations: This test calls validate_api_key_remote_host directly to protect a credential-safety rule.

Call graph: calls 1 internal fn (validate_api_key_remote_host); 1 external calls (assert_eq!).

fn exec_server_remote_api_key_auth_rejects_suffix_spoof()

Purpose: Checks that a malicious domain ending with an OpenAI-looking prefix is not accepted.

Data flow: It validates a spoofed hostname and asserts the standard API-key safety error.

Call relations: This test guards the domain matching inside validate_api_key_remote_host.

Call graph: calls 1 internal fn (validate_api_key_remote_host); 1 external calls (assert_eq!).

fn finalize_resume_from_args(args: &[&str]) -> TuiCli

Purpose: Test helper that parses CLI text and returns the final resume TUI settings.

Data flow: It receives argument strings, parses them as MultitoolCli, extracts the resume command pieces, calls finalize_resume_interactive, and returns the result.

Call relations: Many resume tests use this helper instead of repeating parser setup.

Call graph: calls 1 internal fn (finalize_resume_interactive); 2 external calls (try_parse_from, unreachable!).

fn finalize_fork_from_args(args: &[&str]) -> TuiCli

Purpose: Test helper that parses CLI text and returns the final fork TUI settings.

Data flow: It receives argument strings, parses them, extracts fork command fields, calls finalize_fork_interactive, and returns the result.

Call relations: Fork behavior tests call this helper.

Call graph: calls 1 internal fn (finalize_fork_interactive); 2 external calls (try_parse_from, unreachable!).

fn finalize_archive_from_args(args: &[&str]) -> (String, TuiCli, InteractiveRemoteOptions)

Purpose: Test helper that parses archive CLI text and returns the target, final TUI settings, and remote options.

Data flow: It receives argument strings, parses them, extracts archive command fields, calls finalize_session_archive_interactive, and returns the pieces tests need.

Call relations: Archive merge tests use this helper.

Call graph: calls 1 internal fn (finalize_session_archive_interactive); 2 external calls (try_parse_from, unreachable!).

fn profile_v2_for_args(args: &[&str]) -> anyhow::Result<Option<String>>

Purpose: Test helper that checks how profile selection applies to a parsed command.

Data flow: It receives argument strings, parses them, and either returns the root profile for plain interactive use or calls profile_v2_for_subcommand for subcommands.

Call relations: Profile allowance and rejection tests use this helper.

Call graph: calls 1 internal fn (profile_v2_for_subcommand); 1 external calls (try_parse_from).

fn profile_v2_is_rejected_for_config_management_subcommands()

Purpose: Verifies that --profile is not accepted for configuration-management commands such as feature listing.

Data flow: It parses a feature-list command with a profile and asserts the profile check returns an error.

Call relations: This protects the rules in profile_v2_for_subcommand.

Call graph: 1 external calls (assert!).

fn profile_v2_is_allowed_for_runtime_subcommands()

Purpose: Verifies that runtime commands may use --profile.

Data flow: It tries resume, debug prompt-input, mcp, and sandbox commands with a profile and asserts the profile name is returned.

Call relations: This protects allowed branches in profile_v2_for_subcommand.

Call graph: 1 external calls (assert_eq!).

fn import_remains_an_interactive_prompt()

Purpose: Ensures codex import is treated as a prompt to the interactive UI, not as a subcommand.

Data flow: It parses codex import, checks no subcommand was selected, and checks the prompt text is import.

Call relations: This test protects user-facing parsing behavior in MultitoolCli.

Call graph: 3 external calls (assert!, assert_eq!, try_parse_from).

fn profile_v2_rejects_non_plain_names_at_parse_time()

Purpose: Ensures profile names cannot contain path-like separators.

Data flow: It tries to parse a nested profile name and expects parsing to fail.

Call relations: This test protects profile-name validation from the CLI type parser.

Call graph: 1 external calls (assert!).

fn exec_resume_last_accepts_prompt_positional()

Purpose: Checks that non-interactive exec resume --last can accept a prompt positional.

Data flow: It parses the command, extracts the exec resume arguments, and asserts last is true, session id is absent, and prompt text is kept.

Call relations: This guards parsing behavior in the exec subcommand integration.

Call graph: 4 external calls (assert!, assert_eq!, try_parse_from, panic!).

fn exec_resume_accepts_output_flags_after_subcommand()

Purpose: Checks that exec resume accepts output-related flags after the nested resume command.

Data flow: It parses a command with session id, output file, output schema, and prompt, then asserts all fields land in the expected places.

Call relations: This protects exec command-line compatibility.

Call graph: 3 external calls (assert_eq!, try_parse_from, panic!).

fn dangerous_bypass_conflicts_with_approval_policy()

Purpose: Ensures a broad unsafe bypass flag cannot be combined with an explicit approval policy.

Data flow: It parses conflicting flags and asserts the parser reports an argument conflict.

Call relations: This test protects safety-related clap configuration.

Call graph: 2 external calls (assert_eq!, try_parse_from).

fn app_server_from_args(args: &[&str]) -> AppServerCommand

Purpose: Test helper that parses an app-server command and returns its parsed struct.

Data flow: It receives argument strings, parses them, extracts the app-server subcommand, and returns it.

Call relations: Many app-server parsing tests use this helper.

Call graph: 2 external calls (try_parse_from, unreachable!).

fn default_app_server_socket_path() -> AbsolutePathBuf

Purpose: Test helper that computes the default app-server control socket path.

Data flow: It finds Codex home, asks the app-server code for the control socket path, and returns it.

Call relations: App-server Unix socket parsing tests use this expected value.

Call graph: calls 1 internal fn (find_codex_home); 1 external calls (app_server_control_socket_path).

fn debug_prompt_input_parses_prompt_and_images()

Purpose: Checks that debug prompt-input reads a prompt and comma-separated images.

Data flow: It parses the command and asserts the prompt and image path list match expectations.

Call relations: This protects parser setup for DebugPromptInputCommand.

Call graph: 3 external calls (assert_eq!, try_parse_from, panic!).

fn debug_models_parses_bundled_flag()

Purpose: Checks that debug models --bundled sets the bundled-catalog flag.

Data flow: It parses the command, extracts the debug models struct, and asserts bundled is true.

Call relations: This protects parser setup for DebugModelsCommand.

Call graph: 3 external calls (assert!, try_parse_from, panic!).

fn responses_subcommand_is_not_registered()

Purpose: Ensures an old or unwanted responses subcommand is not exposed.

Data flow: It builds the command definition and asserts none of its subcommands is named responses.

Call relations: This protects the public CLI surface.

Call graph: 2 external calls (assert!, command).

fn help_from_args(args: &[&str]) -> String

Purpose: Test helper that captures help text for a command.

Data flow: It receives argument strings, expects parsing to stop with a help-display result, and returns that help text.

Call relations: Plugin marketplace help tests use this helper.

Call graph: 2 external calls (assert_eq!, try_parse_from).

fn plugin_marketplace_help_uses_plugin_namespace()

Purpose: Checks that marketplace plugin help appears under codex plugin marketplace.

Data flow: It captures help for marketplace and its nested commands and asserts the usage lines use the plugin namespace.

Call relations: This guards the CLI organization for marketplace plugin commands.

Call graph: 2 external calls (assert!, help_from_args).

fn plugin_marketplace_add_parses_under_plugin()

Purpose: Checks that marketplace add is parsed as a plugin command.

Data flow: It parses codex plugin marketplace add ... and asserts the selected top-level subcommand is Plugin.

Call relations: This protects plugin command routing in cli_main.

Call graph: 2 external calls (assert!, try_parse_from).

fn plugin_marketplace_upgrade_parses_under_plugin()

Purpose: Checks that marketplace upgrade is parsed below plugin.

Data flow: It parses the command and asserts the top-level subcommand is Plugin.

Call relations: This protects marketplace command nesting.

Call graph: 2 external calls (assert!, try_parse_from).

fn plugin_add_parses_under_plugin()

Purpose: Checks that plugin add with marketplace options stays under the plugin command.

Data flow: It parses the command and asserts the selected top-level subcommand is Plugin.

Call relations: This protects plugin command routing.

Call graph: 2 external calls (assert!, try_parse_from).

fn plugin_list_parses_under_plugin()

Purpose: Checks that plugin list with marketplace options stays under the plugin command.

Data flow: It parses the command and asserts the selected top-level subcommand is Plugin.

Call relations: This protects plugin command routing.

Call graph: 2 external calls (assert!, try_parse_from).

fn plugin_remove_parses_under_plugin()

Purpose: Checks that plugin remove with marketplace options stays under the plugin command.

Data flow: It parses the command and asserts the selected top-level subcommand is Plugin.

Call relations: This protects plugin command routing.

Call graph: 2 external calls (assert!, try_parse_from).

fn update_parses_as_update_subcommand()

Purpose: Checks that codex update selects the update subcommand.

Data flow: It parses codex update and asserts the parsed subcommand is Update.

Call relations: This protects routing to run_update_command.

Call graph: 2 external calls (assert!, try_parse_from).

fn archive_merges_scoped_tui_flags()

Purpose: Checks that archive commands correctly merge root and archive-scoped TUI flags.

Data flow: It parses a complex archive command, finalizes archive settings, and asserts target, remote, model, profile, working directory, strict config, and hook-trust fields.

Call relations: This protects finalize_session_archive_interactive.

Call graph: 3 external calls (assert!, assert_eq!, finalize_archive_from_args).

fn delete_force_requires_uuid()

Purpose: Checks that forced deletion is only allowed for UUID session ids.

Data flow: It calls delete_action with a UUID and a name, expecting success for the UUID and a clear error for the name.

Call relations: This protects the safety rule in delete_action.

Call graph: calls 1 internal fn (delete_action); 2 external calls (assert!, assert_eq!).

fn sandbox_parses_permissions_profile()

Purpose: Checks that sandbox permissions profile parsing works with the long flag.

Data flow: It parses a sandbox command, extracts sandbox options, and asserts the permissions profile and command arguments.

Call relations: This protects platform sandbox CLI parsing.

Call graph: 3 external calls (assert_eq!, try_parse_from, panic!).

fn sandbox_parses_permissions_profile_short_alias()

Purpose: Checks that the short -P permissions profile flag works for sandbox commands.

Data flow: It parses the command and asserts the permissions profile and trailing command.

Call relations: This protects sandbox CLI shorthand behavior.

Call graph: 3 external calls (assert_eq!, try_parse_from, panic!).

fn sandbox_parses_config_profile()

Purpose: Checks that sandbox config profile parsing works.

Data flow: It parses a sandbox command with --profile and asserts the profile and command arguments.

Call relations: This protects sandbox profile handling.

Call graph: 3 external calls (assert_eq!, try_parse_from, panic!).

fn sandbox_rejects_explicit_profile_controls_without_profile()

Purpose: Checks that sandbox profile-dependent controls require a profile.

Data flow: It parses an invalid sandbox command and asserts the parser reports a missing required argument.

Call relations: This protects sandbox argument constraints.

Call graph: 2 external calls (assert_eq!, try_parse_from).

fn plugin_marketplace_remove_parses_under_plugin()

Purpose: Checks that marketplace remove is parsed under the plugin command.

Data flow: It parses the command and asserts the top-level subcommand is Plugin.

Call relations: This protects marketplace command nesting.

Call graph: 2 external calls (assert!, try_parse_from).

fn marketplace_no_longer_parses_at_top_level()

Purpose: Ensures marketplace commands are not accepted as top-level commands.

Data flow: It tries top-level marketplace add, upgrade, and remove commands and asserts parsing fails.

Call relations: This protects the intended plugin namespace.

Call graph: 2 external calls (assert!, try_parse_from).

fn full_auto_no_longer_parses_at_top_level()

Purpose: Ensures the removed top-level --full-auto flag is not accepted.

Data flow: It parses codex --full-auto and asserts parsing fails.

Call relations: This protects the cleaned-up root CLI surface.

Call graph: 2 external calls (assert!, try_parse_from).

fn exec_full_auto_reports_migration_path()

Purpose: Checks that exec still recognizes removed --full-auto enough to show migration guidance.

Data flow: It parses an exec command with --full-auto, extracts the exec options, and asserts the warning text points to the new sandbox flag.

Call relations: This protects backward-compatible guidance in the exec CLI.

Call graph: 3 external calls (assert_eq!, try_parse_from, panic!).

fn sandbox_full_auto_no_longer_parses()

Purpose: Ensures sandbox does not accept the removed --full-auto flag.

Data flow: It parses an invalid sandbox command and asserts parsing fails.

Call relations: This protects sandbox CLI cleanup.

Call graph: 2 external calls (assert!, try_parse_from).

fn sample_exit_info(conversation_id: Option<&str>, thread_name: Option<&str>) -> AppExitInfo

Purpose: Test helper that creates a sample interactive exit result.

Data flow: It receives optional conversation id and thread name, builds token usage and resume hint data, and returns an AppExitInfo.

Call relations: Exit message formatting tests use this helper.

Call graph: 2 external calls (default, resume_hint).

fn format_exit_messages_skips_zero_usage()

Purpose: Checks that no token line is printed when token usage is zero.

Data flow: It builds a default exit info, calls format_exit_messages, and asserts the returned lines are empty.

Call relations: This protects format_exit_messages output.

Call graph: calls 1 internal fn (format_exit_messages); 2 external calls (assert!, default).

fn format_exit_messages_includes_session_id_for_fatal_exit_without_resume_hint()

Purpose: Checks that fatal exits still show the session id when no resume hint exists.

Data flow: It builds fatal exit info with a thread id, formats messages, and asserts the session-id line.

Call relations: This protects fatal-exit behavior in format_exit_messages.

Call graph: calls 2 internal fn (format_exit_messages, from_string); 3 external calls (assert_eq!, default, Fatal).

fn format_exit_messages_includes_resume_hint_for_fatal_exit()

Purpose: Checks that fatal exits prefer a resume hint when one is available.

Data flow: It builds sample exit info, marks it fatal, formats messages, and asserts token usage plus resume command text.

Call relations: This protects resume guidance in format_exit_messages.

Call graph: calls 1 internal fn (format_exit_messages); 3 external calls (assert_eq!, sample_exit_info, Fatal).

fn format_exit_messages_includes_resume_hint_without_color()

Purpose: Checks normal resume hint text when color is disabled.

Data flow: It builds sample exit info, formats messages without color, and asserts exact text.

Call relations: This protects non-colored terminal output.

Call graph: calls 1 internal fn (format_exit_messages); 2 external calls (assert_eq!, sample_exit_info).

fn format_exit_messages_applies_color_when_enabled()

Purpose: Checks that resume commands are colorized when color support is enabled.

Data flow: It formats sample exit info with color enabled and asserts the resume line contains an ANSI color escape.

Call relations: This protects colored output in format_exit_messages.

Call graph: calls 1 internal fn (format_exit_messages); 3 external calls (assert!, assert_eq!, sample_exit_info).

fn format_exit_messages_names_picker_item_when_thread_has_name()

Purpose: Checks that resume guidance includes the saved thread name when available.

Data flow: It builds sample exit info with a thread name, formats messages, and asserts the picker-style resume hint.

Call relations: This protects named-session resume messaging.

Call graph: calls 1 internal fn (format_exit_messages); 2 external calls (assert_eq!, sample_exit_info).

fn resume_model_flag_applies_when_no_root_flags()

Purpose: Checks that a model flag on resume applies to the final TUI config.

Data flow: It finalizes resume settings from CLI args and asserts the model and resume picker state.

Call relations: This protects finalize_resume_interactive.

Call graph: 3 external calls (assert!, assert_eq!, finalize_resume_from_args).

fn resume_picker_logic_none_and_not_last()

Purpose: Checks that plain codex resume opens the session picker.

Data flow: It finalizes resume settings and asserts picker is on, last is off, and no session id is set.

Call relations: This protects resume selection logic.

Call graph: 3 external calls (assert!, assert_eq!, finalize_resume_from_args).

fn resume_picker_logic_last()

Purpose: Checks that codex resume --last uses the latest session without opening the picker.

Data flow: It finalizes resume settings and asserts last is on, picker is off, and no explicit session id is set.

Call relations: This protects resume --last behavior.

Call graph: 3 external calls (assert!, assert_eq!, finalize_resume_from_args).

fn resume_last_accepts_prompt_positional()

Purpose: Checks that resume --last may treat one positional argument as a prompt.

Data flow: It finalizes settings from --last plus text and asserts the prompt is stored while no session id is set.

Call relations: This protects the special reinterpretation in finalize_resume_interactive.

Call graph: 3 external calls (assert!, assert_eq!, finalize_resume_from_args).

fn resume_last_rejects_explicit_session_and_prompt()

Purpose: Checks that resume --last rejects both a session id and a prompt.

Data flow: It parses the ambiguous command and asserts an argument conflict.

Call relations: This protects the parser customization in SessionTuiCli.

Call graph: 2 external calls (assert_eq!, try_parse_from).

fn resume_picker_logic_with_session_id()

Purpose: Checks that codex resume SESSION targets that session directly.

Data flow: It finalizes resume settings and asserts picker and last are off while the session id is set.

Call relations: This protects resume selection logic.

Call graph: 3 external calls (assert!, assert_eq!, finalize_resume_from_args).

fn resume_with_session_id_accepts_prompt_positional()

Purpose: Checks that resume with a session id can also include a prompt.

Data flow: It finalizes settings from session id plus prompt and asserts both are stored correctly.

Call relations: This protects resume argument handling.

Call graph: 3 external calls (assert!, assert_eq!, finalize_resume_from_args).

fn resume_all_flag_sets_show_all()

Purpose: Checks that resume --all disables current-directory filtering in the picker.

Data flow: It finalizes resume settings and asserts picker is on and show-all is true.

Call relations: This protects resume picker option handling.

Call graph: 2 external calls (assert!, finalize_resume_from_args).

fn resume_include_non_interactive_flag_sets_source_filter_override()

Purpose: Checks that resume can include non-interactive sessions in selection.

Data flow: It finalizes resume settings with the flag and asserts the include-non-interactive field is true.

Call relations: This protects resume filtering behavior.

Call graph: 2 external calls (assert!, finalize_resume_from_args).

fn resume_merges_option_flags()

Purpose: Checks that many resume-scoped runtime flags merge into final interactive settings.

Data flow: It parses a resume command with model, profile, sandbox, approval, search, directory, strict config, and images, then asserts all final fields.

Call relations: This protects merge_interactive_cli_flags and finalize_resume_interactive.

Call graph: 4 external calls (assert!, assert_eq!, assert_matches!, finalize_resume_from_args).

fn resume_merges_dangerously_bypass_flag()

Purpose: Checks that resume accepts and applies the broad bypass flag.

Data flow: It finalizes resume settings with the bypass flag and asserts the final TUI config contains it.

Call relations: This protects resume flag merging.

Call graph: 3 external calls (assert!, assert_eq!, finalize_resume_from_args).

fn resume_merges_bypass_hook_trust_flag()

Purpose: Checks that resume applies the hook-trust bypass flag.

Data flow: It finalizes resume settings with the hook-trust bypass flag and asserts it is true.

Call relations: This protects resume flag merging.

Call graph: 3 external calls (assert!, assert_eq!, finalize_resume_from_args).

fn fork_picker_logic_none_and_not_last()

Purpose: Checks that plain codex fork opens a session picker.

Data flow: It finalizes fork settings and asserts picker is on, last is off, and no session id is set.

Call relations: This protects fork selection logic.

Call graph: 3 external calls (assert!, assert_eq!, finalize_fork_from_args).

fn fork_picker_logic_last()

Purpose: Checks that fork --last uses the latest session without opening the picker.

Data flow: It finalizes fork settings and asserts last is on, picker is off, and no session id is set.

Call relations: This protects fork --last behavior.

Call graph: 3 external calls (assert!, assert_eq!, finalize_fork_from_args).

fn fork_last_accepts_prompt_positional()

Purpose: Checks that fork --last may treat one positional argument as a prompt.

Data flow: It finalizes fork settings and asserts prompt text is stored while session id stays absent.

Call relations: This protects finalize_fork_interactive.

Call graph: 3 external calls (assert!, assert_eq!, finalize_fork_from_args).

fn fork_last_rejects_explicit_session_and_prompt()

Purpose: Checks that fork --last rejects an explicit session plus prompt.

Data flow: It parses the ambiguous command and asserts an argument conflict.

Call relations: This protects the parser customization in SessionTuiCli.

Call graph: 2 external calls (assert_eq!, try_parse_from).

fn fork_picker_logic_with_session_id()

Purpose: Checks that codex fork SESSION targets that session directly.

Data flow: It finalizes fork settings and asserts picker and last are off while the session id is set.

Call relations: This protects fork selection logic.

Call graph: 3 external calls (assert!, assert_eq!, finalize_fork_from_args).

fn fork_with_session_id_accepts_prompt_positional()

Purpose: Checks that fork with a session id can also include a prompt.

Data flow: It finalizes fork settings and asserts both session id and prompt are stored.

Call relations: This protects fork argument handling.

Call graph: 3 external calls (assert!, assert_eq!, finalize_fork_from_args).

fn fork_all_flag_sets_show_all()

Purpose: Checks that fork --all enables showing all sessions in the picker.

Data flow: It finalizes fork settings and asserts picker and show-all are true.

Call relations: This protects fork picker option handling.

Call graph: 2 external calls (assert!, finalize_fork_from_args).

fn app_server_analytics_default_disabled_without_flag()

Purpose: Checks default app-server startup settings.

Data flow: It parses codex app-server and asserts analytics default is disabled, remote control startup flag is off, and transport defaults to stdio.

Call relations: This protects app-server CLI defaults.

Call graph: 3 external calls (assert!, assert_eq!, app_server_from_args).

fn app_server_remote_control_startup_flag_enables_remote_control()

Purpose: Checks that the app-server remote-control startup flag parses.

Data flow: It parses app-server with --remote-control and asserts the field is true.

Call relations: This protects app-server startup option parsing.

Call graph: 2 external calls (assert!, app_server_from_args).

fn app_server_analytics_default_enabled_with_flag()

Purpose: Checks that app-server analytics can be default-enabled by flag.

Data flow: It parses app-server with --analytics-default-enabled and asserts the field is true.

Call relations: This protects app-server analytics option parsing.

Call graph: 2 external calls (assert!, app_server_from_args).

fn strict_config_parses_for_supported_commands()

Purpose: Checks that --strict-config parses for commands that support it.

Data flow: It parses root TUI, mcp-server, review, and exec-server strict-config examples and asserts the flags are set.

Call relations: This protects strict-config parser placement.

Call graph: 3 external calls (assert!, assert_matches!, try_parse_from).

fn root_strict_config_is_supported_for_exec_server()

Purpose: Checks that root-level strict config may be inherited by exec-server.

Data flow: It parses a root strict exec-server command and asserts the rejection helper succeeds.

Call relations: This protects reject_root_strict_config_for_subcommand.

Call graph: calls 1 internal fn (reject_root_strict_config_for_subcommand); 1 external calls (try_parse_from).

fn root_strict_config_is_rejected_for_unsupported_subcommands()

Purpose: Checks that unsupported commands reject root-level strict config with clear names.

Data flow: It parses strict mcp and remote-control commands, calls the rejection helper, and asserts exact error messages.

Call relations: This protects strict-config rejection logic.

Call graph: calls 1 internal fn (reject_root_strict_config_for_subcommand); 2 external calls (assert_eq!, try_parse_from).

fn app_server_subcommands_reject_strict_config()

Purpose: Checks that app-server tooling subcommands reject strict config.

Data flow: It parses app-server proxy with strict config, calls the app-server rejection helper, and asserts the exact error.

Call relations: This protects reject_strict_config_for_app_server_subcommand.

Call graph: calls 1 internal fn (reject_strict_config_for_app_server_subcommand); 2 external calls (assert_eq!, app_server_from_args).

fn reject_remote_flag_for_remote_control()

Purpose: Checks that remote TUI options are rejected for remote-control tooling.

Data flow: It parses a root remote-control command with --remote, calls the rejection helper, and asserts the message mentions remote-control.

Call relations: This protects reject_remote_mode_for_subcommand.

Call graph: calls 1 internal fn (reject_remote_mode_for_subcommand); 4 external calls (assert!, assert_eq!, try_parse_from, panic!).

fn remote_flag_parses_for_interactive_root()

Purpose: Checks that the root interactive command accepts --remote.

Data flow: It parses a root command with a Unix remote address and asserts the remote field is set.

Call relations: This protects interactive remote parsing.

Call graph: 2 external calls (assert_eq!, try_parse_from).

fn remote_auth_token_env_flag_parses_for_interactive_root()

Purpose: Checks that the root interactive command accepts a remote auth token environment variable.

Data flow: It parses remote auth and remote address flags and asserts the environment variable name is stored.

Call relations: This protects interactive remote-auth parsing.

Call graph: 2 external calls (assert_eq!, try_parse_from).

fn remote_flag_parses_for_resume_subcommand()

Purpose: Checks that codex resume can specify its own remote endpoint.

Data flow: It parses a resume command with --remote and asserts the resume remote field is set.

Call relations: This protects resume remote parsing.

Call graph: 3 external calls (assert_eq!, try_parse_from, panic!).

fn reject_remote_mode_for_non_interactive_subcommands()

Purpose: Checks that non-interactive commands reject --remote.

Data flow: It calls the remote rejection helper with a remote address and asserts the error explains the option is only for interactive TUI commands.

Call relations: This protects reject_remote_mode_for_subcommand.

Call graph: calls 1 internal fn (reject_remote_mode_for_subcommand); 1 external calls (assert!).

fn reject_remote_auth_token_env_for_non_interactive_subcommands()

Purpose: Checks that non-interactive commands reject --remote-auth-token-env.

Data flow: It calls the remote rejection helper with an auth-token env var and asserts the error explains the option is only for interactive TUI commands.

Call relations: This protects reject_remote_mode_for_subcommand.

Call graph: calls 1 internal fn (reject_remote_mode_for_subcommand); 1 external calls (assert!).

fn reject_remote_auth_token_env_for_app_server_generate_internal_json_schema()

Purpose: Checks that app-server schema-generation tooling rejects remote auth flags with a precise command name.

Data flow: It builds a generate-internal-json-schema subcommand, calls app-server remote rejection, and asserts the error mentions the nested command.

Call relations: This protects reject_remote_mode_for_app_server_subcommand.

Call graph: calls 1 internal fn (reject_remote_mode_for_app_server_subcommand); 3 external calls (from, assert!, GenerateInternalJsonSchema).

fn read_remote_auth_token_from_env_var_reports_missing_values()

Purpose: Checks the error for a missing remote auth token environment variable.

Data flow: It calls the injectable environment reader with a fake missing variable and asserts the error says it is not set.

Call relations: This protects read_remote_auth_token_from_env_var_with.

Call graph: calls 1 internal fn (read_remote_auth_token_from_env_var_with); 1 external calls (assert!).

fn read_remote_auth_token_from_env_var_trims_values()

Purpose: Checks that remote auth token values are trimmed.

Data flow: It calls the injectable environment reader with a value containing spaces and asserts the returned token has no surrounding whitespace.

Call relations: This protects token cleanup in read_remote_auth_token_from_env_var_with.

Call graph: calls 1 internal fn (read_remote_auth_token_from_env_var_with); 1 external calls (assert_eq!).

fn read_remote_auth_token_from_env_var_rejects_empty_values()

Purpose: Checks that whitespace-only remote auth tokens are rejected.

Data flow: It calls the injectable environment reader with whitespace and asserts the error says the variable is empty.

Call relations: This protects token validation in read_remote_auth_token_from_env_var_with.

Call graph: calls 1 internal fn (read_remote_auth_token_from_env_var_with); 1 external calls (assert!).

fn app_server_listen_websocket_url_parses()

Purpose: Checks that app-server WebSocket listen URLs parse correctly.

Data flow: It parses an app-server command with a ws:// listen URL and asserts the transport contains the expected bind address.

Call relations: This protects app-server transport parsing.

Call graph: 2 external calls (assert_eq!, app_server_from_args).

fn app_server_listen_stdio_url_parses()

Purpose: Checks that stdio:// listen URLs select stdio transport.

Data flow: It parses the app-server command and asserts the transport is stdio.

Call relations: This protects app-server transport parsing.

Call graph: 2 external calls (assert_eq!, app_server_from_args).

fn app_server_stdio_flag_parses()

Purpose: Checks that the app-server --stdio shortcut parses.

Data flow: It parses app-server with --stdio and asserts the boolean flag is true.

Call relations: This protects app-server transport option parsing.

Call graph: 2 external calls (assert!, app_server_from_args).

fn app_server_stdio_flag_conflicts_with_listen()

Purpose: Checks that users cannot specify both --stdio and --listen.

Data flow: It parses a command with both flags and asserts an argument conflict.

Call relations: This protects app-server parser constraints.

Call graph: 2 external calls (assert_eq!, try_parse_from).

fn app_server_listen_unix_socket_url_parses()

Purpose: Checks that unix:// listen URLs use the default control socket path.

Data flow: It parses the command and asserts the transport is a Unix socket at the expected default path.

Call relations: This protects app-server Unix socket parsing.

Call graph: 2 external calls (assert_eq!, app_server_from_args).

fn app_server_listen_unix_socket_path_parses()

Purpose: Checks that explicit Unix socket paths in listen URLs parse correctly.

Data flow: It parses a unix:///tmp/codex.sock listen URL and asserts the transport contains that absolute path.

Call relations: This protects app-server Unix socket parsing.

Call graph: 2 external calls (assert_eq!, app_server_from_args).

fn app_server_listen_off_parses()

Purpose: Checks that app-server listen mode can be turned off.

Data flow: It parses --listen off and asserts the transport is Off.

Call relations: This protects app-server transport parsing.

Call graph: 2 external calls (assert_eq!, app_server_from_args).

fn app_server_listen_invalid_url_fails_to_parse()

Purpose: Checks that unsupported listen URLs are rejected.

Data flow: It parses an app-server command with an HTTP URL and asserts parsing fails.

Call relations: This protects app-server transport validation.

Call graph: 2 external calls (assert!, try_parse_from).

fn app_server_proxy_subcommand_parses()

Purpose: Checks that app-server proxy parses with no socket path.

Data flow: It parses the command and asserts the nested subcommand is Proxy with no socket path set.

Call relations: This protects app-server proxy command parsing.

Call graph: 2 external calls (assert!, app_server_from_args).

fn app_server_daemon_subcommands_parse()

Purpose: Checks that all app-server daemon lifecycle subcommands parse.

Data flow: It parses bootstrap, start, restart, enable/disable remote control, stop, and version commands and asserts each maps to the expected enum variant.

Call relations: This protects app-server daemon command routing.

Call graph: 1 external calls (assert!).

fn app_server_proxy_sock_path_parses()

Purpose: Checks that app-server proxy accepts a socket path.

Data flow: It parses app-server proxy --sock codex.sock, extracts the proxy command, and asserts the path was resolved relative to the current directory.

Call relations: This protects parse_socket_path as used by proxy parsing.

Call graph: 3 external calls (assert_eq!, app_server_from_args, panic!).

fn reject_remote_auth_token_env_for_app_server_proxy()

Purpose: Checks that app-server proxy rejects remote auth token flags.

Data flow: It builds a proxy subcommand, calls app-server remote rejection, and asserts the error mentions app-server proxy.

Call relations: This protects reject_remote_mode_for_app_server_subcommand.

Call graph: calls 1 internal fn (reject_remote_mode_for_app_server_subcommand); 2 external calls (assert!, Proxy).

fn reject_remote_auth_token_env_for_app_server_version()

Purpose: Checks that app-server daemon version rejects remote auth token flags.

Data flow: It builds the daemon version subcommand, calls app-server remote rejection, and asserts the error mentions the nested command.

Call relations: This protects reject_remote_mode_for_app_server_subcommand.

Call graph: calls 1 internal fn (reject_remote_mode_for_app_server_subcommand); 2 external calls (assert!, Daemon).

fn app_server_capability_token_flags_parse()

Purpose: Checks parsing for app-server WebSocket capability-token authentication.

Data flow: It parses auth mode and token-file flags and asserts the parsed auth settings match.

Call relations: This protects app-server WebSocket auth CLI parsing.

Call graph: 2 external calls (assert_eq!, app_server_from_args).

fn app_server_signed_bearer_flags_parse()

Purpose: Checks parsing for app-server signed bearer token authentication.

Data flow: It parses shared secret, issuer, audience, and clock-skew flags and asserts all fields are stored correctly.

Call relations: This protects app-server WebSocket auth CLI parsing.

Call graph: 2 external calls (assert_eq!, app_server_from_args).

fn app_server_rejects_removed_insecure_non_loopback_flag()

Purpose: Ensures a removed insecure app-server flag is not accepted.

Data flow: It tries to parse the removed flag and asserts parsing fails.

Call relations: This protects the app-server CLI from reintroducing unsafe compatibility.

Call graph: 2 external calls (assert!, try_parse_from).

fn features_enable_parses_feature_name()

Purpose: Checks that features enable captures the feature name.

Data flow: It parses the command, extracts the feature enable arguments, and asserts the feature string.

Call relations: This protects feature command parsing.

Call graph: 3 external calls (assert_eq!, try_parse_from, panic!).

fn features_disable_parses_feature_name()

Purpose: Checks that features disable captures the feature name.

Data flow: It parses the command, extracts the feature disable arguments, and asserts the feature string.

Call relations: This protects feature command parsing.

Call graph: 3 external calls (assert_eq!, try_parse_from, panic!).

fn feature_toggles_known_features_generate_overrides()

Purpose: Checks that known --enable and --disable flags become config overrides.

Data flow: It builds a FeatureToggles value, calls to_overrides, and asserts the generated override strings.

Call relations: This protects FeatureToggles::to_overrides.

Call graph: 2 external calls (assert_eq!, vec!).

fn feature_toggles_accept_legacy_linux_sandbox_flag()

Purpose: Checks that a legacy Linux sandbox feature key is still accepted.

Data flow: It builds toggles with the legacy feature, converts to overrides, and asserts the expected override string.

Call relations: This protects compatibility in feature-key validation.

Call graph: 3 external calls (new, assert_eq!, vec!).

fn feature_toggles_accept_removed_image_detail_original_flag()

Purpose: Checks that a removed image-detail feature key is still recognized for compatibility.

Data flow: It builds toggles with that feature, converts to overrides, and asserts the generated string.

Call relations: This protects feature-key compatibility.

Call graph: 3 external calls (new, assert_eq!, vec!).

fn feature_toggles_unknown_feature_errors()

Purpose: Checks that unknown feature flags are rejected.

Data flow: It builds toggles with a fake feature, calls to_overrides, and asserts the error text.

Call relations: This protects FeatureToggles::validate_feature.

Call graph: 3 external calls (new, assert_eq!, vec!).

fn strict_config_with_unknown_enable_errors()

Purpose: Checks that strict config plus an unknown --enable feature reports the unknown feature.

Data flow: It uses the strict-config helper with an unknown enable flag and asserts the error text.

Call relations: This protects feature validation during strict root parsing.

Call graph: 2 external calls (assert_eq!, strict_config_feature_toggle_error).

fn strict_config_with_unknown_disable_errors()

Purpose: Checks that strict config plus an unknown --disable feature reports the unknown feature.

Data flow: It uses the strict-config helper with an unknown disable flag and asserts the error text.

Call relations: This protects feature validation during strict root parsing.

Call graph: 2 external calls (assert_eq!, strict_config_feature_toggle_error).

fn strict_config_with_compound_enable_errors()

Purpose: Checks that compound-looking unknown feature names are rejected as unknown.

Data flow: It uses the strict-config helper with a dotted feature name and asserts the exact unknown-feature error.

Call relations: This protects feature flag name validation.

Call graph: 2 external calls (assert_eq!, strict_config_feature_toggle_error).

fn strict_config_feature_toggle_error(args: &[&str]) -> anyhow::Error

Purpose: Test helper that parses strict-config plus feature toggle arguments and returns the validation error.

Data flow: It builds full CLI arguments, parses them, asserts strict config is set, then calls to_overrides and returns the expected error.

Call relations: Strict-config feature toggle tests use this helper.

Call graph: 3 external calls (assert!, try_parse_from, once).

fn deref(&self) -> &Self::Target

Purpose: This lets a Cli value be read as if it were its embedded shared command-line options. It is a convenience so other code can access common Codex settings without repeatedly writing through the shared field.

Data flow: It receives a reference to the full TUI command-line settings. It looks inside the shared wrapper and returns a read-only reference to the common SharedCliOptions stored there. Nothing is changed.

Call relations: This supports code that wants common CLI settings from a Cli object. Rather than copying or converting anything, it simply points callers to the shared options already stored inside the TUI CLI structure.

fn deref_mut(&mut self) -> &mut Self::Target

Purpose: This lets a Cli value be changed as if it were its embedded shared command-line options. It is useful when setup code needs to adjust common options after parsing.

Data flow: It receives a mutable reference to the full TUI command-line settings. It reaches into the shared wrapper and returns a mutable reference to the common SharedCliOptions, allowing the caller to edit those shared fields in place.

Call relations: This is the writable companion to Cli::deref. It fits into startup configuration code that treats TUI-specific settings and shared Codex settings as one combined set of options.

fn into_inner(self) -> SharedCliOptions

Purpose: This unwraps the TUI wrapper and gives back the plain shared command-line options. It is used when later code no longer needs the TUI-specific wrapper.

Data flow: It takes ownership of a TuiSharedCliOptions value. It removes the outer wrapper and returns the contained SharedCliOptions. The wrapper itself is consumed.

Call relations: This function is the exit door from the wrapper type. After parsing and TUI-specific command setup are done, other code can call this to work directly with the shared options.

fn deref(&self) -> &Self::Target

Purpose: This lets the wrapper be read like the shared options it contains. It keeps the wrapper lightweight while still making shared fields easy to access.

Data flow: It receives a read-only reference to TuiSharedCliOptions. It returns a read-only reference to the inner SharedCliOptions. No data is copied or changed.

Call relations: This supports the wrapper’s main job: add TUI-specific parsing behavior while still behaving like the shared options in normal use.

fn deref_mut(&mut self) -> &mut Self::Target

Purpose: This lets the wrapper be edited like the shared options it contains. It allows callers to update common settings without manually unpacking the wrapper.

Data flow: It receives a mutable reference to TuiSharedCliOptions. It returns a mutable reference to the inner SharedCliOptions, so changes go directly into the stored shared options.

Call relations: This works alongside TuiSharedCliOptions::deref to make the wrapper mostly transparent to the rest of the startup code.

fn augment_args(cmd: clap::Command) -> clap::Command

Purpose: This adds the shared Codex command-line flags to the TUI command definition, then applies the TUI’s extra rule about conflicting approval options. It is part of teaching the parser what flags are valid.

Data flow: It receives a Clap command builder, which is an object describing accepted command-line arguments. It first asks the shared options type to add its normal arguments, then passes the result to mark_tui_args so the TUI-specific conflict rule is added. It returns the updated command builder.

Call relations: The command-line parser calls this while building the TUI command. This function delegates the common work to the shared options implementation, then hands the command to mark_tui_args for the TUI-only adjustment.

Call graph: calls 1 internal fn (mark_tui_args); 1 external calls (augment_args).

fn augment_args_for_update(cmd: clap::Command) -> clap::Command

Purpose: This updates an existing command definition with shared Codex flags and the TUI-specific conflict rule. It is used in parser flows where arguments are being added to an already-built command.

Data flow: It receives a Clap command builder. It asks the shared options type to add update-style argument definitions, then sends that command through mark_tui_args. The returned command includes both the shared options and the TUI conflict rule.

Call relations: Like TuiSharedCliOptions::augment_args, this is called by the argument parsing framework. It follows the same two-step path: shared option setup first, then mark_tui_args to adapt the result for the TUI.

Call graph: calls 1 internal fn (mark_tui_args); 1 external calls (augment_args_for_update).

fn from_arg_matches(matches: &clap::ArgMatches) -> Result<Self, clap::Error>

Purpose: This creates a TuiSharedCliOptions value from parsed command-line matches. In other words, it turns the parser’s raw findings into the wrapper type used by the TUI.

Data flow: It receives parsed argument matches from Clap. It asks SharedCliOptions to read its values from those matches. If that succeeds, it wraps the shared options in TuiSharedCliOptions; if parsing fails, it returns the parsing error.

Call relations: The parsing framework calls this after command-line text has been matched against known flags. This function relies on the shared options parser, then packages the result in the TUI wrapper.

Call graph: 1 external calls (from_arg_matches).

fn update_from_arg_matches(&mut self, matches: &clap::ArgMatches) -> Result<(), clap::Error>

Purpose: This updates an existing TuiSharedCliOptions value using newly parsed command-line matches. It is useful when options are parsed or refreshed in stages.

Data flow: It receives a mutable wrapper and parsed argument matches. It forwards those matches to the inner SharedCliOptions, which updates itself. The result is either success or a Clap parsing error.

Call relations: This keeps the wrapper in sync with Clap’s update flow. Instead of doing its own parsing, it passes the work directly to the shared options stored inside it.

fn mark_tui_args(cmd: clap::Command) -> clap::Command

Purpose: This applies a TUI-specific safety rule to the command-line definition: the dangerous bypass option cannot be used together with the normal approval policy option. It prevents a confusing or unsafe combination of flags.

Data flow: It receives a Clap command builder. It finds the shared argument named dangerously_bypass_approvals_and_sandbox and marks it as conflicting with approval_policy. It returns the modified command builder.

Call relations: This helper is called by both TUI argument-building paths: TuiSharedCliOptions::augment_args and TuiSharedCliOptions::augment_args_for_update. They build the shared argument list first, then call this function to add the TUI’s extra conflict rule before parsing is used.

Call graph: called by 2 (augment_args, augment_args_for_update); 1 external calls (mut_arg).

fn format_exit_messages(exit_info: AppExitInfo, color_enabled: bool) -> Vec<String>

Purpose: This function turns the app’s final status into short human-readable lines to print after the TUI closes. It decides whether to show token usage, a resume command, or a session ID for troubleshooting.

Data flow: It receives an AppExitInfo, which is a bundle of facts about how the app ended, plus a yes/no value saying whether colored terminal output is safe. It checks whether the exit was fatal, pulls out token usage, session ID, and resume instructions, then builds a list of text lines. The result is a vector of strings ready to print; it does not print them itself.

Call relations: After main gets the final app result from run_main, it calls this helper to prepare the closing messages. This keeps the printing decision simple in main: main only loops over the returned lines and writes them to standard output.

Call graph: 3 external calls (new, format!, matches!).

fn main() -> anyhow::Result<()>

Purpose: This is the program’s main entry point. It parses command-line input, starts the Codex TUI, prints final information, and returns an error status if the run failed badly.

Data flow: It starts with the process arguments supplied by the shell. It parses them into TopCli, moves top-level configuration overrides into the inner TUI command, and passes that command plus launch-path information into run_main. When the app returns exit information, main prints any fatal error, asks whether stdout supports color, prints formatted exit messages, flushes stdout if needed, and exits with code 1 for fatal failures or success otherwise.

Call relations: The first thing it does is hand control to arg0_dispatch_or_else, which decides how to launch based on the executable name and then runs the async startup block. Inside that block, main calls the TUI’s run_main to do the real app work, then calls format_exit_messages to translate the app’s final state into user-facing closing text.

Call graph: 1 external calls (arg0_dispatch_or_else).

fn deref(&self) -> &Self::Target

Purpose: This lets a Cli value be used as if it were its shared command-line options. It is a convenience so other code can read common options without first digging through the shared field.

Data flow: It receives a reference to the full parsed Cli value. It looks inside the wrapped shared options and returns a reference to the underlying shared option structure; it does not change anything.

Call relations: After command-line parsing has produced a Cli, any later code that expects the common shared options can rely on this shortcut instead of manually accessing cli.shared.0.

fn deref_mut(&mut self) -> &mut Self::Target

Purpose: This lets code modify the shared command-line options through a mutable Cli value. It is the writable version of the same convenience provided by Cli::deref.

Data flow: It receives a mutable reference to the full Cli. It returns a mutable reference to the underlying shared options, allowing the caller to update those shared settings in place.

Call relations: It fits into setup code that may adjust parsed command-line settings before the exec command actually runs.

fn removed_full_auto_warning(&self) -> Option<&'static str>

Purpose: This checks whether the user typed the old hidden --full-auto flag and, if so, returns a warning telling them what to use instead. It preserves a friendlier upgrade path for people with old scripts or habits.

Data flow: It reads the removed_full_auto boolean from the parsed command line. If the flag was present, it returns a fixed warning message; otherwise it returns no message.

Call relations: After parsing, startup code can call this to decide whether to print a compatibility warning before continuing with the requested exec behavior.

fn into_inner(self) -> SharedCliOptions

Purpose: This unwraps ExecSharedCliOptions and gives back the shared command-line options it contains. It is used when the caller no longer needs the exec-specific wrapper.

Data flow: It takes ownership of the wrapper. It removes the outer layer and returns the inner SharedCliOptions value unchanged.

Call relations: Once parsing and exec-specific argument setup are finished, later code can call this to pass the common options into shared configuration-loading or runtime code.

fn deref(&self) -> &Self::Target

Purpose: This lets the exec-specific wrapper be read like the shared options it contains. It avoids repetitive wrapper-unwrapping code.

Data flow: It receives a reference to ExecSharedCliOptions. It returns a reference to the inner SharedCliOptions; nothing is copied or changed.

Call relations: Code that works with common Codex options can use this wrapper naturally during command setup and validation.

fn deref_mut(&mut self) -> &mut Self::Target

Purpose: This lets code edit the shared options inside the exec-specific wrapper. It is useful when the parser or setup code needs to update common settings in place.

Data flow: It receives a mutable reference to the wrapper. It returns a mutable reference to the inner shared options so the caller can change them.

Call relations: It supports the argument parsing and update flow by making ExecSharedCliOptions behave like the shared options it wraps.

fn augment_args(cmd: clap::Command) -> clap::Command

Purpose: This tells the command-line parser how to add the shared Codex options to the codex exec command, with a few of them made usable anywhere in the command. In command-line parser terms, these are “global” flags, meaning they apply even when typed after a subcommand.

Data flow: It receives a partially built parser command. It asks the shared options code to add its usual arguments, then passes that parser through mark_exec_global_args to mark selected options as global, and returns the updated parser.

Call relations: The parser-building process calls this while constructing the codex exec interface. It hands off to the shared option builder first, then to mark_exec_global_args for exec-specific tweaks.

Call graph: calls 1 internal fn (mark_exec_global_args); 1 external calls (augment_args).

fn augment_args_for_update(cmd: clap::Command) -> clap::Command

Purpose: This is the update-mode version of augment_args: it teaches the parser how to update existing shared exec options from new matches. It applies the same exec-specific global-flag behavior.

Data flow: It receives a parser command used for updating arguments. It lets the shared options code add update-capable arguments, then marks selected arguments as global, and returns the modified parser.

Call relations: When the command-line parser needs to support updating an existing options value, it calls this. The function again delegates the common work to shared code and uses mark_exec_global_args for the exec-specific adjustment.

Call graph: calls 1 internal fn (mark_exec_global_args); 1 external calls (augment_args_for_update).

fn from_arg_matches(matches: &clap::ArgMatches) -> Result<Self, clap::Error>

Purpose: This builds ExecSharedCliOptions from the parser’s raw results. It converts matched command-line text into the shared options wrapper used by this exec command.

Data flow: It receives ArgMatches, which are the parser’s structured record of what the user typed. It asks SharedCliOptions to parse its own fields, wraps the result in ExecSharedCliOptions, and returns either that wrapper or a parse error.

Call relations: The command-line parser calls this after matching arguments. This function relies on the shared options parser so exec does not duplicate common option parsing.

Call graph: 1 external calls (from_arg_matches).

fn update_from_arg_matches(&mut self, matches: &clap::ArgMatches) -> Result<(), clap::Error>

Purpose: This updates an existing ExecSharedCliOptions value using newly parsed command-line matches. It is used when the parser needs to refresh an already-created options object.

Data flow: It receives a mutable wrapper and parser matches. It passes the matches to the inner SharedCliOptions, which updates itself or reports a parsing error.

Call relations: This is part of the parser’s update path. Rather than replacing the wrapper itself, it lets the inner shared options object apply the changes.

fn mark_exec_global_args(cmd: clap::Command) -> clap::Command

Purpose: This marks a small set of shared options as global for codex exec, so users can type them before or after a subcommand. It makes the command-line experience more forgiving and consistent.

Data flow: It receives a parser command that already contains arguments. It finds the model, dangerously_bypass_approvals_and_sandbox, and bypass_hook_trust arguments, marks each one as global, and returns the changed parser command.

Call relations: Both ExecSharedCliOptions::augment_args and ExecSharedCliOptions::augment_args_for_update call this after the shared options have been added. It performs the exec-specific finishing touch on the parser definition.

Call graph: called by 2 (augment_args, augment_args_for_update); 1 external calls (mut_arg).

fn from(raw: ResumeArgsRaw) -> Self

Purpose: This converts the raw parser shape for resume into the cleaner form the rest of the program wants. Its key job is to reinterpret a positional value as a prompt when the user says --last and did not provide a separate prompt.

Data flow: It receives ResumeArgsRaw, which directly reflects what the command-line parser can express. If --last is set and there is no explicit prompt, it moves the positional session_id value into prompt and clears session_id; otherwise it keeps both values as parsed. It then returns a ResumeArgs value with the corrected meaning.

Call relations: The parser first creates ResumeArgsRaw. ResumeArgs::from_arg_matches and ResumeArgs::update_from_arg_matches then call this conversion so the rest of the resume flow sees the intended session id, prompt, image list, and flags.

fn augment_args(cmd: clap::Command) -> clap::Command

Purpose: This tells the command-line parser which arguments the resume subcommand accepts. It delegates to the raw resume argument shape because that is the form the parser can describe directly.

Data flow: It receives a parser command for the resume subcommand. It passes that command to ResumeArgsRaw’s argument builder and returns the resulting command.

Call relations: During parser construction, this function supplies the visible resume options and positional values. The later conversion step fixes the conditional meaning that the parser cannot express on its own.

Call graph: 1 external calls (augment_args).

fn augment_args_for_update(cmd: clap::Command) -> clap::Command

Purpose: This is the update-mode parser builder for resume arguments. It keeps the parser’s update behavior aligned with the same raw resume argument layout.

Data flow: It receives a parser command meant for updating argument values. It delegates to ResumeArgsRaw’s update argument builder and returns the updated command.

Call relations: The command-line parser uses this when it needs to update an existing ResumeArgs value. As with normal parsing, the raw shape is built first and later converted into the cleaned-up ResumeArgs form.

Call graph: 1 external calls (augment_args_for_update).

fn from_arg_matches(matches: &clap::ArgMatches) -> Result<Self, clap::Error>

Purpose: This builds a clean ResumeArgs value from the parser’s matched command-line input. It makes sure the special --last positional-value rule is applied before other code sees the result.

Data flow: It receives parser matches. It first parses them into ResumeArgsRaw; if that succeeds, it converts the raw value through ResumeArgs::from and returns the cleaned ResumeArgs, otherwise it returns the parser error.

Call relations: After the user runs codex exec resume ..., the parser calls this to produce the resume settings. It hands off raw parsing to ResumeArgsRaw and meaning-correction to ResumeArgs::from.

Call graph: 1 external calls (from_arg_matches).

fn update_from_arg_matches(&mut self, matches: &clap::ArgMatches) -> Result<(), clap::Error>

Purpose: This replaces an existing ResumeArgs value with one newly parsed from command-line matches. It ensures updates use the same special --last interpretation as first-time parsing.

Data flow: It receives a mutable ResumeArgs and parser matches. It parses the matches into ResumeArgsRaw, converts that into a cleaned ResumeArgs, stores it over the old value, and returns success or a parsing error.

Call relations: This is used by the parser’s update flow for the resume subcommand. It reuses the same raw parsing and conversion path so updated resume arguments behave exactly like freshly parsed ones.

Call graph: 1 external calls (from_arg_matches).

fn parse_attempts(input: &str) -> Result<usize, String>

Purpose: This function checks the user’s requested number of task attempts. It makes sure the value is a whole number and stays within the allowed range of 1 through 4.

Data flow: It receives text from a command-line flag, such as --attempts 3 or --attempt 2. It tries to turn that text into a number, then checks whether the number is between 1 and 4. If the input is valid, it returns the number; if not, it returns a clear error message that clap can show to the user.

Call relations: During command-line parsing, clap calls this function for fields that use attempt counts, such as creating a task with multiple assistant attempts or choosing which attempt to apply or display. Once this function approves the value, the parsed command structs carry a safe number to the later task-running, diff, or apply logic.

fn parse_limit(input: &str) -> Result<i64, String>

Purpose: This function checks the maximum number of cloud tasks the user wants to list. It keeps the list size reasonable by allowing only whole numbers from 1 through 20.

Data flow: It receives the text written after the list command’s --limit flag. It parses that text into a number, verifies that the number falls between 1 and 20, and then returns it. If the text is not a number or is outside the allowed range, it returns an explanatory error message instead.

Call relations: Clap calls this function while parsing the list command. If the value passes, the list command receives a valid limit to send into the task-listing flow; if it fails, parsing stops early and the user sees the validation error before any cloud request is made.

async fn init_backend(user_agent_suffix: &str) -> anyhow::Result<BackendContext>

Purpose: Creates the connection object used to talk to Cloud Tasks. It also checks whether the user is signed in and makes sure requests carry the right identity and user-agent information.

Data flow: It takes a short label describing which part of the cloud feature is running. It reads environment variables, sets the user-agent suffix, optionally chooses a mock backend in debug mode, loads saved authentication, attaches authentication to the HTTP client, logs useful startup details, and returns a backend context containing the backend object and base URL. If the user is not signed in correctly, it prints guidance and exits.

Call relations: All command flows and the interactive UI call this before doing cloud work. It hands back the shared backend that later functions use for creating, listing, reading, and applying tasks.

Call graph: calls 5 internal fn (new, append_error_log, load_auth_manager, set_user_agent_suffix, get_codex_user_agent); called by 6 (run_apply_command, run_diff_command, run_exec_command, run_list_command, run_main, run_status_command); 7 external calls (new, auth_provider_from_auth, eprintln!, format!, matches!, var, exit).

async fn default_branch_name(&self, path: &std::path::Path) -> Option<String>

Purpose: Asks Git what the repository’s default branch is, such as main or master.

Data flow: It receives a filesystem path, passes that path to the Git utility function, and returns the branch name if Git can find one.

Call relations: It is the real implementation behind the Git information interface. resolve_git_ref_with_git_info uses it when there is no explicit branch and no current branch could be found.

Call graph: 1 external calls (default_branch_name).

async fn current_branch_name(&self, path: &std::path::Path) -> Option<String>

Purpose: Asks Git which branch the current checkout is on.

Data flow: It receives a filesystem path, asks the Git helper for the current branch at that path, and returns the branch name if available.

Call relations: It is used by resolve_git_ref_with_git_info through the RealGitInfo provider. Tests replace it with a stub so branch-choice behavior can be checked without a real Git repository.

Call graph: 1 external calls (current_branch_name).

async fn resolve_git_ref(branch_override: Option<&String>) -> String

Purpose: Chooses the Git branch name to send when creating a cloud task.

Data flow: It receives an optional branch override from the user. It delegates the actual decision to resolve_git_ref_with_git_info using real Git lookups, and returns the chosen branch name.

Call relations: run_exec_command calls this before creating a task. It is a thin production wrapper around the more testable branch-resolution function.

Call graph: calls 1 internal fn (resolve_git_ref_with_git_info); called by 1 (run_exec_command).

async fn resolve_git_ref_with_git_info(
    branch_override: Option<&String>,
    git_info: &impl GitInfoProvider,
) -> String

Purpose: Decides which branch name should be used, with a clear fallback order.

Data flow: It first checks whether the user supplied a non-empty branch override. If not, it looks at the current working directory, asks for the current Git branch, then the default branch, and finally falls back to main if nothing else is known.

Call relations: resolve_git_ref uses this in normal operation. The branch-related tests call it directly with fake Git information to confirm each fallback path.

Call graph: called by 6 (resolve_git_ref, branch_override_is_used_when_provided, falls_back_to_current_branch_when_default_is_missing, falls_back_to_main_when_no_git_info_is_available, prefers_current_branch_when_available, trims_override_whitespace); 3 external calls (current_branch_name, default_branch_name, current_dir).

async fn run_exec_command(args: crate::cli::ExecCommand) -> anyhow::Result<()>

Purpose: Implements the non-interactive command that creates a new cloud task and prints its URL.

Data flow: It receives command arguments containing the prompt, environment, optional branch, and attempt count. It connects to the backend, reads the prompt from the argument or standard input, resolves the environment and branch, creates the task remotely, builds a web URL for it, and prints that URL.

Call relations: run_main dispatches here when the user runs the exec subcommand. It relies on the backend initializer, input reader, environment resolver, branch resolver, and cloud client task creation call.

Call graph: calls 5 internal fn (init_backend, resolve_environment_id, resolve_git_ref, resolve_query_input, task_url); called by 1 (run_main); 2 external calls (create_task, println!).

async fn resolve_environment_id(ctx: &BackendContext, requested: &str) -> anyhow::Result<String>

Purpose: Turns what the user typed for an environment into the exact environment ID expected by the backend.

Data flow: It receives the backend context and a requested environment string. It trims the string, fetches the available environments, then matches either an exact ID or a case-insensitive label. It returns the matching ID, or an understandable error if none or several different matches are found.

Call relations: run_exec_command uses this before creating a task, and run_list_command uses it when filtering tasks. It calls the environment-detection module to get the current list of environments.

Call graph: calls 3 internal fn (list_environments, build_chatgpt_headers, normalize_base_url); called by 2 (run_exec_command, run_list_command); 1 external calls (anyhow!).

fn resolve_query_input(query_arg: Option<String>) -> anyhow::Result<String>

Purpose: Gets the text prompt for a new cloud task from either the command line or standard input.

Data flow: It receives an optional query argument. If a normal string is present, it returns that. If the argument is -, or if input is being piped in, it reads all of standard input. It rejects missing or empty input with a clear error.

Call relations: run_exec_command calls this so users can create tasks either with codex cloud exec "..." or by piping longer text into the command.

Call graph: called by 1 (run_exec_command); 5 external calls (new, anyhow!, eprintln!, matches!, stdin).

fn parse_task_id(raw: &str) -> anyhow::Result<codex_cloud_tasks_client::TaskId>

Purpose: Accepts either a raw task ID or a full task URL and extracts the task ID.

Data flow: It receives a string, trims it, removes any URL fragment or query string, takes the last path segment if it looks like a URL, and wraps the result as a TaskId. Empty input becomes an error.

Call relations: The status, diff, and apply commands all use this so users can paste either task_... or a browser URL. Tests also check that both forms work.

Call graph: called by 5 (run_apply_command, run_diff_command, run_status_command, collect_attempt_diffs_includes_sibling_attempts, parse_task_id_from_url_and_raw); 2 external calls (bail!, TaskId).

fn cmp_attempt(lhs: &AttemptDiffData, rhs: &AttemptDiffData) -> Ordering

Purpose: Defines the order for multiple attempts of the same task.

Data flow: It receives two attempt records. It compares their explicit placement numbers first, then their creation times if placement is missing, and returns which one should come first.

Call relations: collect_attempt_diffs uses this after gathering diffs from the main task and sibling attempts, so attempt selection is stable and human-friendly.

async fn collect_attempt_diffs(
    backend: &dyn codex_cloud_tasks_client::CloudBackend,
    task_id: &codex_cloud_tasks_client::TaskId,
) -> anyhow::Result<Vec<AttemptDiffData>>

Purpose: Fetches all available diffs for a task, including alternate attempts, and sorts them.

Data flow: It receives a backend and task ID. It fetches task text metadata, fetches the main task diff if present, then asks for sibling attempts when a turn ID is available. It keeps only attempts with diffs, sorts them, and returns the list. If no diff exists, it returns an error saying the task may still be running.

Call relations: The diff and apply commands call this before choosing which attempt to print or apply. A test uses the mock backend to confirm sibling attempts are included.

Call graph: called by 3 (run_apply_command, run_diff_command, collect_attempt_diffs_includes_sibling_attempts); 6 external calls (new, bail!, get_task_diff, get_task_text, list_sibling_attempts, clone).

fn select_attempt(
    attempts: &[AttemptDiffData],
    attempt: Option<usize>,
) -> anyhow::Result<&AttemptDiffData>

Purpose: Picks one attempt from a list using the user’s one-based attempt number.

Data flow: It receives the collected attempts and an optional attempt number. If no number is supplied, it chooses attempt 1. It converts the human-friendly number to a zero-based index, checks bounds, and returns the selected attempt or an error.

Call relations: run_diff_command and run_apply_command use this after collect_attempt_diffs. The bounds-checking behavior is covered by a test.

Call graph: called by 3 (run_apply_command, run_diff_command, select_attempt_validates_bounds); 3 external calls (bail!, is_empty, len).

fn task_status_label(status: &TaskStatus) -> &'static str

Purpose: Converts an internal task status into the short uppercase text shown to users.

Data flow: It receives a task status value and returns labels such as PENDING, READY, APPLIED, or ERROR.

Call relations: format_task_status_lines calls it when building human-readable status output.

Call graph: called by 1 (format_task_status_lines).

fn summary_line(summary: &codex_cloud_tasks_client::DiffSummary, colorize: bool) -> String

Purpose: Builds the small diff summary line shown under a task, such as added lines, removed lines, and changed files.

Data flow: It receives a diff summary and a color setting. If there is no diff, it returns no diff. Otherwise it formats added and removed line counts and file count, optionally coloring additions green, deletions red, and secondary text dim.

Call relations: format_task_status_lines uses it as the third line of each task summary.

Call graph: called by 1 (format_task_status_lines); 1 external calls (format!).

fn format_task_status_lines(
    task: &codex_cloud_tasks_client::TaskSummary,
    now: chrono::DateTime<Utc>,
    colorize: bool,
) -> Vec<String>

Purpose: Turns one task summary into the few lines of text shown in status and list output.

Data flow: It receives a task, the current time, and whether color is allowed. It formats the status and title, chooses an environment label or ID, calculates a relative update time, adds a diff summary, and returns the resulting lines.

Call relations: run_status_command prints these lines for one task, while format_task_list_lines uses them for every task in a list. Tests verify the plain-text output.

Call graph: calls 3 internal fn (summary_line, task_status_label, format_relative_time); called by 4 (format_task_list_lines, run_status_command, format_task_status_lines_with_diff_and_label, format_task_status_lines_without_diff_falls_back); 2 external calls (new, format!).

fn format_task_list_lines(
    tasks: &[codex_cloud_tasks_client::TaskSummary],
    base_url: &str,
    now: chrono::DateTime<Utc>,
    colorize: bool,
) -> Vec<String>

Purpose: Formats a whole page of tasks for command-line display.

Data flow: It receives task summaries, the base URL, current time, and color setting. For each task it builds the web URL, indents the status lines, and inserts blank lines between tasks.

Call relations: run_list_command calls this when the user wants normal text output rather than JSON. A test checks that URLs and status blocks are arranged correctly.

Call graph: calls 2 internal fn (format_task_status_lines, task_url); called by 2 (run_list_command, format_task_list_lines_formats_urls); 5 external calls (new, new, iter, len, format!).

async fn run_status_command(args: crate::cli::StatusCommand) -> anyhow::Result<()>

Purpose: Implements the command that checks one task’s current status.

Data flow: It connects to the backend, parses the task ID, fetches the task summary, formats it, and prints it. If the task is not ready, it exits with a failure code so scripts can detect that the task is not done yet.

Call relations: run_main dispatches here for the status subcommand. It reuses task ID parsing, backend setup, and status formatting.

Call graph: calls 3 internal fn (format_task_status_lines, init_backend, parse_task_id); called by 1 (run_main); 6 external calls (now, get_task_summary, matches!, println!, exit, on).

async fn run_list_command(args: crate::cli::ListCommand) -> anyhow::Result<()>

Purpose: Implements the command that lists cloud tasks, optionally filtered by environment.

Data flow: It connects to the backend, resolves an environment filter if provided, fetches a page of tasks, and then either prints JSON or readable text. If another page exists, it prints the command needed to fetch it.

Call relations: run_main dispatches here for the list subcommand. It combines backend listing, environment resolution, text formatting, and JSON output.

Call graph: calls 3 internal fn (format_task_list_lines, init_backend, resolve_environment_id); called by 1 (run_main); 6 external calls (now, list_tasks, format!, println!, json!, on).

async fn run_diff_command(args: crate::cli::DiffCommand) -> anyhow::Result<()>

Purpose: Implements the command that prints a task’s diff to standard output.

Data flow: It connects to the backend, parses the task ID, collects all available attempt diffs, selects the requested attempt, and prints the raw diff text.

Call relations: run_main dispatches here for the diff subcommand. It depends on the shared attempt collection and selection helpers.

Call graph: calls 4 internal fn (collect_attempt_diffs, init_backend, parse_task_id, select_attempt); called by 1 (run_main); 1 external calls (print!).

async fn run_apply_command(args: crate::cli::ApplyCommand) -> anyhow::Result<()>

Purpose: Implements the command that applies a task’s diff outside the interactive UI.

Data flow: It connects to the backend, parses the task ID, collects attempt diffs, chooses the requested attempt, sends that diff to the backend’s apply operation, and prints the result message. If applying did not fully succeed, it exits with failure.

Call relations: run_main dispatches here for the apply subcommand. The interactive UI has separate background helpers for apply and preflight, but this command follows the same basic idea synchronously.

Call graph: calls 4 internal fn (collect_attempt_diffs, init_backend, parse_task_id, select_attempt); called by 1 (run_main); 4 external calls (apply_task, matches!, println!, exit).

fn level_from_status(status: codex_cloud_tasks_client::ApplyStatus) -> app::ApplyResultLevel

Purpose: Converts a backend apply result into the simpler result level used by the UI.

Data flow: It receives an apply status from the cloud client and maps it to a UI level: success, partial, or error.

Call relations: spawn_preflight uses this when turning a backend preflight response into an app event for the terminal UI.

Call graph: called by 1 (spawn_preflight).

fn spawn_preflight(
    app: &mut app::App,
    backend: &Arc<dyn codex_cloud_tasks_client::CloudBackend>,
    tx: &UnboundedSender<app::AppEvent>,
    frame_tx: &UnboundedSender<Instant>,
    title:

Purpose: Starts a background dry-run check before applying a diff in the interactive UI.

Data flow: It receives the app state, backend, event channel, redraw channel, task title, and apply job. It first refuses to start if another apply or preflight is already running. Otherwise it marks preflight as in progress, schedules a redraw, spawns an asynchronous task, calls the backend preflight API, and sends a finished event with the message, level, skipped paths, and conflicts.

Call relations: The UI calls this when the user asks to apply a task or presses the preflight key in the apply modal. It reports back through AppEvent::ApplyPreflightFinished, which run_main later consumes.

Call graph: calls 1 internal fn (level_from_status); 8 external calls (from_millis, now, clone, send, new, apply_task_preflight, format!, spawn).

fn spawn_apply(
    app: &mut app::App,
    backend: &Arc<dyn codex_cloud_tasks_client::CloudBackend>,
    tx: &UnboundedSender<app::AppEvent>,
    frame_tx: &UnboundedSender<Instant>,
    job: ApplyJ

Purpose: Starts the real apply operation in the background from the interactive UI.

Data flow: It receives the app state, backend, channels, and apply job. It refuses to start if an apply or preflight is already running, marks apply as in progress, schedules a redraw, spawns an asynchronous task, calls the backend apply API, and sends an ApplyFinished event with either the outcome or an error string.

Call relations: The apply confirmation modal in run_main calls this after the user confirms. The event it sends is later handled in the main UI loop to update status, close modals, and refresh the task list after success.

Call graph: 7 external calls (from_millis, now, clone, send, apply_task, format!, spawn).

async fn run_main(cli: Cli, _codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()>

Purpose: Runs the codex cloud subcommand, either by dispatching a one-shot command or by launching the full interactive terminal UI.

Data flow: It receives parsed CLI options. If a subcommand is present, it forwards to the matching command runner. Otherwise it sets up logging, initializes the backend, switches the terminal into full-screen raw mode, creates app state, starts background loads for tasks and environments, listens for keyboard and paste events, receives backend results through channels, updates state, redraws the UI, and finally restores the terminal before returning.

Call relations: This is the main hub of the file. It calls the command runners for non-interactive use, and for interactive use it coordinates app, ui, environment detection, task loading, diff loading, preflight/apply helpers, and terminal event handling.

Call graph: calls 13 internal fn (new, load_tasks, autodetect_environment_id, list_environments, init_backend, run_apply_command, run_diff_command, run_exec_command, run_list_command, run_status_command (+3 more)); 21 external calls (clone, new, try_from_default_env, new, now, from_std, EnvironmentAutodetected, EnvironmentsLoaded, execute!, format! (+11 more)).

fn conversation_lines(prompt: Option<String>, messages: &[String]) -> Vec<String>

Purpose: Turns a prompt and assistant messages into simple labeled text for the task details view.

Data flow: It receives an optional user prompt and a list of assistant messages. It writes user: followed by prompt lines, then assistant: followed by message lines, with blank lines where helpful. If there is nothing to show, it returns <no output>.

Call relations: run_main uses this when backend task text arrives, so the details overlay can show the conversation in a readable form.

Call graph: 2 external calls (new, new).

fn pretty_lines_from_error(raw: &str) -> Vec<String>

Purpose: Turns a noisy backend error into a few useful lines for the UI.

Data flow: It receives a raw error string. It first chooses a friendly headline, then tries to find and parse an embedded JSON body for assistant error details, status, or latest event text. If parsing fails, it includes a shortened raw message; if the task is still in progress, it adds a refresh hint.

Call relations: run_main calls this when loading task details fails, so the details overlay shows helpful context instead of a long technical HTTP error.

Call graph: 3 external calls (new, new, format!).

fn new(default_branch: Option<String>, current_branch: Option<String>) -> Self

Purpose: Creates fake Git branch information for tests.

Data flow: It receives optional default and current branch names and stores them in a stub object.

Call relations: The branch-resolution tests use this instead of real Git so each scenario is controlled and repeatable.

async fn default_branch_name(&self, _path: &std::path::Path) -> Option<String>

Purpose: Returns the fake default branch configured for a test.

Data flow: It ignores the path argument and returns a clone of the stored default branch option.

Call relations: resolve_git_ref_with_git_info calls this during tests when it needs default-branch information.

async fn current_branch_name(&self, _path: &std::path::Path) -> Option<String>

Purpose: Returns the fake current branch configured for a test.

Data flow: It ignores the path argument and returns a clone of the stored current branch option.

Call relations: resolve_git_ref_with_git_info calls this during tests when it needs current-branch information.

async fn branch_override_is_used_when_provided()

Purpose: Checks that an explicit branch argument wins over Git detection.

Data flow: It gives resolve_git_ref_with_git_info a branch override and a stub with no Git branches. It expects the returned branch to be the override.

Call relations: This protects the behavior used by task creation when users deliberately choose a branch.

Call graph: calls 1 internal fn (resolve_git_ref_with_git_info); 2 external calls (assert_eq!, new).

async fn trims_override_whitespace()

Purpose: Checks that accidental spaces around a branch override are ignored.

Data flow: It passes an override with leading and trailing spaces, then asserts that the resolved branch has those spaces removed.

Call relations: This supports run_exec_command, where branch input may come from a human typing at the command line.

Call graph: calls 1 internal fn (resolve_git_ref_with_git_info); 2 external calls (assert_eq!, new).

async fn prefers_current_branch_when_available()

Purpose: Checks that the current Git branch is chosen before the default branch.

Data flow: It provides both a fake current branch and fake default branch. It expects the current branch to be returned.

Call relations: This confirms the normal task-creation behavior: cloud work should follow what the developer is currently working on.

Call graph: calls 1 internal fn (resolve_git_ref_with_git_info); 2 external calls (assert_eq!, new).

async fn falls_back_to_current_branch_when_default_is_missing()

Purpose: Checks that a current branch is still used even when no default branch is known.

Data flow: It provides only a fake current branch and expects that branch to be returned.

Call relations: This covers repositories or situations where default-branch detection fails but current-branch detection still works.

Call graph: calls 1 internal fn (resolve_git_ref_with_git_info); 2 external calls (assert_eq!, new).

async fn falls_back_to_main_when_no_git_info_is_available()

Purpose: Checks the final fallback branch name.

Data flow: It provides no fake current branch and no fake default branch. It expects the resolver to return main.

Call relations: This makes sure task creation still has a branch value even outside a usable Git repository.

Call graph: calls 1 internal fn (resolve_git_ref_with_git_info); 2 external calls (assert_eq!, new).

fn format_task_status_lines_with_diff_and_label()

Purpose: Checks readable task formatting when a task has a diff and a friendly environment label.

Data flow: It builds a sample ready task with changed files and line counts, formats it without color, and compares the exact output lines.

Call relations: This protects the output used by both the status command and list command.

Call graph: calls 1 internal fn (format_task_status_lines); 3 external calls (now, assert_eq!, new).

fn format_task_status_lines_without_diff_falls_back()

Purpose: Checks readable task formatting when no diff summary is available.

Data flow: It builds a pending task with an empty diff summary and no environment label, formats it, and expects the environment ID and no diff line.

Call relations: This protects the plain-text output path for tasks that are still running or have no changes.

Call graph: calls 1 internal fn (format_task_status_lines); 4 external calls (now, assert_eq!, default, new).

fn format_task_list_lines_formats_urls()

Purpose: Checks that a list of tasks is formatted with task URLs and indented summaries.

Data flow: It builds two sample tasks, formats them with a ChatGPT base URL, and compares the complete line list including the blank separator.

Call relations: This protects the text output used by run_list_command.

Call graph: calls 1 internal fn (format_task_list_lines); 3 external calls (now, assert_eq!, vec!).

async fn collect_attempt_diffs_includes_sibling_attempts()

Purpose: Checks that diff collection includes alternate attempts, not just the main task.

Data flow: It uses the mock backend and a parsed task URL, collects attempt diffs, and asserts that two ordered attempts with non-empty diffs are returned.

Call relations: This test covers the helper used by the diff and apply commands when users request different attempts.

Call graph: calls 2 internal fn (collect_attempt_diffs, parse_task_id); 2 external calls (assert!, assert_eq!).

fn select_attempt_validates_bounds()

Purpose: Checks that attempt selection accepts valid attempt numbers and rejects missing ones.

Data flow: It creates a one-item attempt list, selects attempt 1 successfully, then checks that selecting attempt 2 returns an error.

Call relations: This protects the validation used before printing or applying a chosen attempt.

Call graph: calls 1 internal fn (select_attempt); 3 external calls (assert!, assert_eq!, vec!).

fn parse_task_id_from_url_and_raw()

Purpose: Checks that task IDs can be read from both raw IDs and full URLs.

Data flow: It parses a raw task ID, parses a URL with a query string, and confirms both return the expected IDs. It also checks that blank input is rejected.

Call relations: This protects the convenience behavior used by status, diff, and apply commands.

Call graph: calls 1 internal fn (parse_task_id); 2 external calls (assert!, assert_eq!).

fn composer_input_renders_typed_characters()

Purpose: Checks that the text composer used for new tasks actually renders typed input and footer hints.

Data flow: It creates a composer, sends it a typed a key, renders into a test buffer, and verifies that the character appears. It then adds hint items, renders again, and checks that the footer contains the hint text.

Call relations: This ignored slow test covers UI input behavior that the interactive new-task page depends on.

Call graph: calls 1 internal fn (new); 7 external calls (empty, Char, new, new, assert!, panic!, vec!).

async fn run_app(cmd: AppCommand) -> anyhow::Result<()>

Purpose: Runs the desktop-app command from the CLI. It prepares the workspace path and then asks the desktop app subsystem to open or install Codex Desktop for that workspace.

Data flow: It receives an AppCommand, which contains the user’s requested workspace path and an optional installer download URL override. It tries to convert the path into a canonical full path; if that fails, it uses the path as originally provided. It then passes the workspace path and optional download URL to the desktop app opener/installer, and returns the success or error result from that operation.

Call relations: This function is called by cli_main when the user invokes the desktop app command. Before handing off, it uses the standard canonicalize filesystem call to clean up the path. Then, on supported desktop platforms, it calls run_app_open_or_install, which takes over the real work of opening the app or installing it first if necessary.

Call graph: calls 1 internal fn (run_app_open_or_install); called by 1 (cli_main); 1 external calls (canonicalize).

async fn run_app_open_or_install(
    workspace: std::path::PathBuf,
    download_url_override: Option<String>,
) -> anyhow::Result<()>

Purpose: This is the shared entry point for desktop app open-or-install behavior, regardless of whether the CLI was built for macOS or Windows. Callers use it so they do not need to know which operating-system-specific code should run.

Data flow: It receives a workspace path and an optional download URL override. It passes those same values to the platform-specific implementation for the current build: the macOS routine on macOS, or the Windows routine on Windows. The result is returned to the caller as either success or an error explaining what went wrong.

Call relations: When run_app reaches the point where the desktop app should be opened or installed, it calls this function. This function then hands the work to run_mac_app_open_or_install or run_windows_app_open_or_install, depending on the operating system the program was compiled for, and passes the final outcome back up to run_app.

Call graph: calls 2 internal fn (run_mac_app_open_or_install, run_windows_app_open_or_install); called by 1 (run_app).

async fn run_mac_app_open_or_install(
    workspace: PathBuf,
    download_url_override: Option<String>,
) -> anyhow::Result<()>

Purpose: This is the main macOS routine for opening Codex Desktop. It either opens an existing installation or downloads, installs, and then opens the app.

Data flow: It receives a workspace path and an optional installer download URL. It first looks for an installed Codex.app. If found, it opens that app with the workspace. If not found, it chooses a download URL, installs the app from that installer, then opens the newly installed app. The result is success if the desktop app was launched, or an error explaining what failed.

Call relations: This function is called by the higher-level app-opening flow, run_app_open_or_install. It coordinates the helper functions: it asks find_existing_codex_app_path whether the app is already present, calls download_and_install_codex_to_user_applications when it is missing, and hands the final app path to open_codex_app.

Call graph: calls 3 internal fn (download_and_install_codex_to_user_applications, find_existing_codex_app_path, open_codex_app); called by 1 (run_app_open_or_install); 1 external calls (eprintln!).

fn is_apple_silicon_mac() -> bool

Purpose: This function decides whether the current Mac should use the Apple Silicon installer. That matters because Apple Silicon and Intel Macs can need different app builds.

Data flow: It reads the process architecture and, on macOS, checks system flags through sysctl, which is a low-level way to ask the operating system about hardware and translation mode. It returns true if the machine appears to be Apple Silicon or running under Apple's translation layer, and false otherwise.

Call relations: It supports the installer choice made by run_mac_app_open_or_install. Although the call graph does not list that inline use directly, its result is used there to choose between the ARM64 and x64 Codex Desktop download URLs.

fn find_existing_codex_app_path() -> Option<PathBuf>

Purpose: This function checks whether Codex Desktop is already installed in one of the expected macOS app locations.

Data flow: It asks candidate_codex_app_paths for possible app paths, then checks each one to see whether it is an existing directory. It returns the first matching path, or nothing if Codex.app is not found.

Call relations: It is called by run_mac_app_open_or_install at the start of the flow. If it finds the app, the larger flow can skip downloading and installing, and go straight to open_codex_app.

Call graph: calls 1 internal fn (candidate_codex_app_paths); called by 1 (run_mac_app_open_or_install).

fn candidate_codex_app_paths() -> Vec<PathBuf>

Purpose: This function builds the short list of places where Codex.app is expected to live on macOS.

Data flow: It always includes /Applications/Codex.app. If the HOME environment variable is available, it also adds ~/Applications/Codex.app. It returns these paths as a list.

Call relations: It is used by find_existing_codex_app_path, which turns this list of guesses into an actual installed-app check.

Call graph: called by 1 (find_existing_codex_app_path); 3 external calls (from, var_os, vec!).

async fn open_codex_app(app_path: &Path, workspace: &Path) -> anyhow::Result<()>

Purpose: This function asks macOS to open Codex Desktop and tells it which workspace folder to use.

Data flow: It receives the path to Codex.app and a workspace path. It turns the workspace into a codex:// deep link using codex_new_thread_url, then runs the macOS open command with the app and that link. It returns success if macOS reports that the app opened, or an error if the command failed.

Call relations: It is called by run_mac_app_open_or_install both when the app was already installed and after a fresh install. It relies on codex_new_thread_url to package the workspace path in the format the desktop app understands.

Call graph: calls 1 internal fn (codex_new_thread_url); called by 1 (run_mac_app_open_or_install); 3 external calls (bail!, new, eprintln!).

fn codex_new_thread_url(workspace: &Path) -> String

Purpose: This function creates the special link that tells Codex Desktop to start a new thread for a particular workspace path.

Data flow: It receives a filesystem path, converts it to text, safely URL-encodes it as a query parameter named path, and returns a string like codex://threads/new?path=.... URL encoding matters because folder names can contain spaces or symbols.

Call relations: It is called by open_codex_app before launching the desktop app. It is also checked by the test tests::codex_new_thread_url_encodes_workspace_path to make sure unusual workspace paths survive the trip correctly.

Call graph: called by 2 (open_codex_app, codex_new_thread_url_encodes_workspace_path); 5 external calls (as_os_str, as_ref, new, format!, new).

async fn download_and_install_codex_to_user_applications(dmg_url: &str) -> anyhow::Result<PathBuf>

Purpose: This function performs the full installer workflow after Codex Desktop is found to be missing.

Data flow: It receives a .dmg download URL. It creates a temporary folder, downloads the disk image there, mounts it, finds the app bundle inside, copies the app into an Applications folder, then detaches the mounted disk image. It returns the path where Codex.app was installed.

Call relations: It is called by run_mac_app_open_or_install when no existing app is found. Inside, it delegates each physical step to focused helpers: download_dmg, mount_dmg, find_codex_app_in_mount, install_codex_app_bundle, and finally detach_dmg for cleanup.

Call graph: calls 5 internal fn (detach_dmg, download_dmg, find_codex_app_in_mount, install_codex_app_bundle, mount_dmg); called by 1 (run_mac_app_open_or_install); 2 external calls (new, eprintln!).

async fn install_codex_app_bundle(app_in_volume: &Path) -> anyhow::Result<PathBuf>

Purpose: This function copies Codex.app from the mounted installer into a real Applications folder.

Data flow: It receives the path to the app bundle inside the mounted disk image. It gets possible destination folders, creates each folder if needed, and tries to place Codex.app there. If the app already exists in a destination, it treats that as success. If copying fails in one destination, it warns and tries the next. It returns the installed app path or an error if all locations fail.

Call relations: It is called by download_and_install_codex_to_user_applications after the installer has been mounted and the app has been found. It uses candidate_applications_dirs to decide where to install and copy_app_bundle to do the actual copy.

Call graph: calls 2 internal fn (candidate_applications_dirs, copy_app_bundle); called by 1 (download_and_install_codex_to_user_applications); 3 external calls (bail!, eprintln!, create_dir_all).

fn candidate_applications_dirs() -> anyhow::Result<Vec<PathBuf>>

Purpose: This function lists the folders where the installer should try to place Codex.app.

Data flow: It starts with the system-wide /Applications folder, then adds the current user's Applications folder. It returns that ordered list, or an error if the user's home folder cannot be determined.

Call relations: It is called by install_codex_app_bundle, which tries these destinations one by one until installation succeeds.

Call graph: calls 1 internal fn (user_applications_dir); called by 1 (install_codex_app_bundle); 1 external calls (vec!).

async fn download_dmg(url: &str, dest: &Path) -> anyhow::Result<()>

Purpose: This function downloads the Codex Desktop installer disk image from the internet.

Data flow: It receives a URL and a destination file path. It runs curl with options to follow redirects, fail on bad HTTP responses, and retry a few times. If curl succeeds, the .dmg file is written at the destination. If it fails, the function returns an error.

Call relations: It is called near the start of download_and_install_codex_to_user_applications, before any mounting or copying can happen.

Call graph: called by 1 (download_and_install_codex_to_user_applications); 3 external calls (bail!, new, eprintln!).

async fn mount_dmg(dmg_path: &Path) -> anyhow::Result<PathBuf>

Purpose: This function opens the downloaded macOS disk image so its contents can be read.

Data flow: It receives the path to a .dmg file and runs hdiutil attach in read-only, no-browse mode. It reads the command output, extracts the /Volumes/... mount point using parse_hdiutil_attach_mount_point, and returns that mount folder. If mounting or parsing fails, it returns an error.

Call relations: It is called by download_and_install_codex_to_user_applications after the installer is downloaded. It hands the mounted volume path to the next step, which searches for Codex.app inside it.

Call graph: calls 1 internal fn (parse_hdiutil_attach_mount_point); called by 1 (download_and_install_codex_to_user_applications); 3 external calls (from_utf8_lossy, bail!, new).

async fn detach_dmg(mount_point: &Path) -> anyhow::Result<()>

Purpose: This function unmounts the installer disk image after installation is done.

Data flow: It receives the mounted volume path and runs hdiutil detach on it. If macOS reports success, it returns successfully. If detaching fails, it returns an error.

Call relations: It is called by download_and_install_codex_to_user_applications after the install attempt, even when the install step failed. The caller treats detach failure as a warning so cleanup problems do not hide the main install result.

Call graph: called by 1 (download_and_install_codex_to_user_applications); 2 external calls (bail!, new).

fn find_codex_app_in_mount(mount_point: &Path) -> anyhow::Result<PathBuf>

Purpose: This function locates the app bundle inside the mounted installer volume.

Data flow: It receives a mount folder. It first checks for the expected Codex.app directly inside that folder. If not found, it scans the top level for any directory ending in .app. It returns the app path it finds, or an error if there is no app bundle.

Call relations: It is called by download_and_install_codex_to_user_applications after mount_dmg succeeds. Its result is passed to install_codex_app_bundle so the app can be copied into Applications.

Call graph: called by 1 (download_and_install_codex_to_user_applications); 3 external calls (join, bail!, read_dir).

async fn copy_app_bundle(src_app: &Path, dest_app: &Path) -> anyhow::Result<()>

Purpose: This function copies the Codex.app bundle from the installer to its final destination.

Data flow: It receives a source app path and a destination app path. It runs macOS's ditto tool, which is commonly used to copy app bundles while preserving their structure and metadata. It returns success if the copy command succeeds, or an error if it fails.

Call relations: It is called by install_codex_app_bundle for each destination folder being tried. The caller decides whether to accept the success or move on to another folder after a failure.

Call graph: called by 1 (install_codex_app_bundle); 2 external calls (bail!, new).

fn user_applications_dir() -> anyhow::Result<PathBuf>

Purpose: This function builds the path to the current user's personal Applications folder.

Data flow: It reads the HOME environment variable. If it exists, it appends Applications and returns that path. If HOME is missing, it returns an error because it cannot safely guess the user's app folder.

Call relations: It is called by candidate_applications_dirs, which includes this user-specific folder as a fallback or alternative install location.

Call graph: called by 1 (candidate_applications_dirs); 2 external calls (from, var_os).

fn parse_hdiutil_attach_mount_point(output: &str) -> Option<String>

Purpose: This function extracts the mounted volume path from the text printed by hdiutil attach.

Data flow: It receives command output as text, looks for a line containing /Volumes/, and then tries to pull out the mount path. It handles both tab-separated output and simpler whitespace-separated output. It returns the mount path as text, or nothing if it cannot find one.

Call relations: It is called by mount_dmg after macOS mounts the installer. The tests check common output shapes, including mount names with spaces, so the installer does not fail just because the volume name is not a single word.

Call graph: called by 1 (mount_dmg).

fn parses_mount_point_from_tab_separated_hdiutil_output()

Purpose: This test confirms that mount-point parsing works for normal tab-separated hdiutil output.

Data flow: It feeds a sample line of hdiutil output into parse_hdiutil_attach_mount_point and checks that the returned value is /Volumes/Codex. The test changes nothing outside itself.

Call relations: It protects the behavior that mount_dmg depends on. If parsing breaks, this test should fail before users see installer failures.

Call graph: 1 external calls (assert_eq!).

fn parses_mount_point_with_spaces()

Purpose: This test confirms that installer volume names with spaces are parsed correctly.

Data flow: It passes sample hdiutil output where the volume is named Codex Installer. It checks that the full path /Volumes/Codex Installer is returned, not just the first word.

Call relations: It supports parse_hdiutil_attach_mount_point, which in turn supports mount_dmg. This matters because macOS volume names often contain spaces.

Call graph: 1 external calls (assert_eq!).

fn codex_new_thread_url_encodes_workspace_path()

Purpose: This test checks that workspace paths are safely placed into the Codex deep link.

Data flow: It builds a deep link for a path containing spaces and a # symbol, parses that link as a URL, and checks that the scheme, host, path, and query value are all correct. Nothing is written to disk or sent to the network.

Call relations: It directly tests codex_new_thread_url, which is used by open_codex_app. This helps ensure the desktop app receives the exact workspace path the user intended.

Call graph: calls 1 internal fn (codex_new_thread_url); 3 external calls (new, assert_eq!, parse).

async fn run_windows_app_open_or_install(
    workspace: PathBuf,
    download_url_override: Option<String>,
) -> anyhow::Result<()>

Purpose: This is the main Windows flow for opening Codex Desktop from the CLI. It either opens the given workspace in the installed app or sends the user to install the app first.

Data flow: It receives a workspace path and, optionally, a replacement download URL. It turns the workspace into a display-friendly string, checks whether Codex Desktop is installed, then chooses what to open: a codex:// app link for an installed app, or an installer/store URL for a missing app. It prints short instructions for the user and returns success or an error if opening something fails.

Call relations: This function is called by run_app_open_or_install, which is the higher-level platform-neutral flow. It relies on codex_app_is_installed to decide which branch to take, display_workspace_path to make messages readable, codex_new_thread_url to build the app-opening link, and open_url to ask Windows to launch either the app link or the installer page.

Call graph: calls 4 internal fn (codex_app_is_installed, codex_new_thread_url, display_workspace_path, open_url); called by 1 (run_app_open_or_install); 2 external calls (display, eprintln!).

async fn codex_app_is_installed() -> anyhow::Result<bool>

Purpose: This function asks Windows whether the Codex Desktop app appears in the Start menu app list. It is used as the yes-or-no gate before trying to open a workspace in the app.

Data flow: It runs a PowerShell command that searches for a Start app named Codex and reads its output. If PowerShell cannot be launched, it returns an error. If the command runs but does not succeed, or if it succeeds with no app ID in the output, it returns false; otherwise it returns true.

Call relations: run_windows_app_open_or_install calls this before doing anything visible to the user. The result decides whether the next step is opening a codex:// workspace link or opening an installer link.

Call graph: called by 1 (run_windows_app_open_or_install); 2 external calls (from_utf8_lossy, new).

async fn open_url(url: &str) -> anyhow::Result<()>

Purpose: This function asks Windows to open a URL or app link using the system’s normal launcher. It is the shared doorway for opening Codex links, installer links, and store pages.

Data flow: It receives a string such as a web address or codex:// link. It starts PowerShell and passes that string to Start-Process, which tells Windows to open it with the appropriate app or browser. If Windows reports success, it returns success; otherwise it returns an error that includes what failed.

Call relations: run_windows_app_open_or_install calls this whenever it needs Windows to open something. The caller decides what URL should be opened, while this function performs the actual operating-system handoff.

Call graph: called by 1 (run_windows_app_open_or_install); 2 external calls (bail!, new).

fn codex_new_thread_url(workspace: &str) -> String

Purpose: This function builds the special Codex Desktop link that means “open a new thread for this workspace.” It also makes sure the workspace path is safely encoded for use inside a URL.

Data flow: It receives a workspace path as text. It puts that path into a URL query parameter named path, escaping characters such as backslashes and colons so the link stays valid. It returns a complete link like codex://threads/new?path=....

Call relations: run_windows_app_open_or_install calls this only after it has confirmed the desktop app is installed. The resulting link is then handed to open_url, which asks Windows to launch it.

Call graph: called by 1 (run_windows_app_open_or_install); 3 external calls (new, format!, new).

fn display_workspace_path(workspace: &Path) -> String

Purpose: This function turns some Windows-internal path formats into cleaner text for the user to read. It keeps normal paths unchanged.

Data flow: It receives a workspace path. If the path starts with Windows’ extended path prefix \\?\, it removes that prefix for display. If it is an extended network path beginning with \\?\UNC\, it converts it back to the familiar \\server\share form. It returns the cleaned-up string.

Call relations: run_windows_app_open_or_install uses this before printing messages. The cleaned path is for human-readable output only; the actual app-opening URL is built separately from the original workspace text.

Call graph: called by 1 (run_windows_app_open_or_install); 2 external calls (display, format!).

fn display_workspace_path_removes_windows_extended_prefix()

Purpose: This test checks that a local Windows path with the extended \\?\ prefix is displayed without that internal prefix.

Data flow: It gives display_workspace_path a path like \\?\C:\... and compares the result with the expected normal-looking C:\... form. The test passes only if the prefix is removed exactly as intended.

Call relations: This test protects the behavior used by run_windows_app_open_or_install when it prints workspace instructions. If someone changes path display logic later, this test warns them if local extended paths become user-unfriendly again.

Call graph: 1 external calls (assert_eq!).

fn display_workspace_path_preserves_unc_prefix()

Purpose: This test checks that an extended Windows network path is converted to the normal network-share form, not mangled.

Data flow: It gives display_workspace_path a path like \\?\UNC\server\share\codex and expects \\server\share\codex. The before-and-after comparison confirms that the network location remains intact while the internal prefix is removed.

Call relations: This test supports the same display path helper used by run_windows_app_open_or_install. It makes sure the helper treats network paths differently from local paths, because Windows writes those extended forms differently.

Call graph: 1 external calls (assert_eq!).

fn display_workspace_path_leaves_regular_paths_unchanged()

Purpose: This test checks that ordinary Windows paths are not changed unnecessarily.

Data flow: It passes a normal path like C:\Users\... into display_workspace_path and expects exactly the same string back. The test confirms that cleanup only happens when there is an extended Windows prefix to remove.

Call relations: This protects the display helper used in the main open-or-install flow. It prevents a future change from accidentally rewriting normal user-facing paths.

Call graph: 1 external calls (assert_eq!).

fn codex_new_thread_url_encodes_windows_workspace_path()

Purpose: This test checks that a normal Windows workspace path is correctly escaped when placed inside a Codex app link.

Data flow: It passes a path containing a drive letter and backslashes into codex_new_thread_url. It expects a codex://threads/new URL where characters such as : and \ have been percent-encoded, which is the standard way to make them safe inside URLs.

Call relations: This test protects the link-building helper used by run_windows_app_open_or_install. If URL encoding breaks, Windows might open the app link but Codex Desktop could receive the wrong workspace path.

Call graph: 1 external calls (assert_eq!).

fn codex_new_thread_url_preserves_verbatim_workspace_path()

Purpose: This test checks that even Windows verbatim paths, including the \\?\ prefix, are preserved when encoded into the Codex app link.

Data flow: It gives codex_new_thread_url a verbatim Windows path and expects the returned URL to contain an encoded version of that exact path. The path is not cleaned for display here; it is preserved as data for the desktop app.

Call relations: This test reinforces the distinction between display text and launch data. display_workspace_path may clean a path for messages, but codex_new_thread_url, used by the main flow, must encode the actual workspace string it was given.

Call graph: 1 external calls (assert_eq!).

fn subcommand_name(&self) -> &'static str

Purpose: Returns a readable name for the selected remote-control command. This is useful for reporting, logging, or analytics that need to know which command shape the user chose.

Data flow: It reads the command’s optional subcommand. If there is no subcommand, it returns remote-control; if the user chose start or stop, it returns the matching full command name.

Call relations: This method sits on the command data type itself. It does not start or stop anything; it simply gives the rest of the CLI a stable label for the command.

async fn run(
    command: RemoteControlCommand,
    arg0_paths: Arg0DispatchPaths,
    root_config_overrides: CliConfigOverrides,
) -> anyhow::Result<()>

Purpose: Runs the remote-control command chosen by the user. It decides whether to start foreground remote control, start the daemon-backed version, or stop remote control.

Data flow: It receives the parsed command, executable dispatch paths, and configuration overrides. It prints a progress message unless JSON mode is enabled, calls the appropriate app-server or daemon operation, then prints the final result.

Call relations: The main CLI calls this function when the remote-control command is selected. It delegates foreground startup to run_foreground_remote_control, daemon startup to the daemon readiness helper, daemon shutdown to the daemon lifecycle helper, and output formatting to the print functions.

Call graph: calls 4 internal fn (print_remote_control_progress, print_remote_control_start_output, print_remote_control_stop_output, run_foreground_remote_control); called by 1 (cli_main); 2 external calls (ensure_remote_control_ready, run).

fn print_remote_control_progress(json: bool, message: &str) -> anyhow::Result<()>

Purpose: Prints a short progress message for humans before a longer remote-control operation starts. It stays silent in JSON mode so machine-readable output is not mixed with extra text.

Data flow: It receives a JSON flag and a message. If JSON is requested, it returns without printing; otherwise it writes the message to standard output and flushes it so the user sees it immediately.

Call relations: run calls this before starting or stopping remote control. It is deliberately separate from final output so progress text can be suppressed for scripts.

Call graph: called by 1 (run); 2 external calls (println!, stdout).

async fn run_foreground_remote_control(
    json: bool,
    arg0_paths: Arg0DispatchPaths,
    root_config_overrides: CliConfigOverrides,
) -> anyhow::Result<()>

Purpose: Starts remote control in the foreground, where the app-server lives only as long as this command is running. This is the no-subcommand behavior of remote-control.

Data flow: It creates a private temporary socket path, builds app-server runtime options with remote control enabled, starts the app-server task, and starts a Ctrl-C watcher. It waits until the server is ready, stopped, failed, or exited too early; then it prints readiness, waits for the server to finish or for Ctrl-C, and cleans up tasks as needed.

Call relations: run calls this for foreground mode. It relies on foreground_stop_signal to notice Ctrl-C, wait_for_foreground_remote_control_start to race startup against cancellation and failure, wait_for_foreground_remote_control_ready to enable remote control through the socket, print_foreground_ready_output to tell the user the server is ready, and wait_for_foreground_app_server or abort_foreground_app_server to finish cleanly.

Call graph: calls 7 internal fn (abort_foreground_app_server, foreground_stop_signal, print_foreground_ready_output, wait_for_foreground_app_server, wait_for_foreground_remote_control_ready, wait_for_foreground_remote_control_start, from_absolute_path); called by 1 (run); 6 external calls (default, default, run_main_with_transport_options, default, new, spawn).

fn foreground_stop_signal() -> (watch::Receiver<bool>, JoinHandle<()>)

Purpose: Creates a small background listener for Ctrl-C. It gives the foreground server flow a shared “stop requested” signal.

Data flow: It creates a watch channel, which is a simple shared value that other async tasks can observe. A spawned task waits for Ctrl-C; when Ctrl-C happens, it changes the shared value from false to true.

Call relations: run_foreground_remote_control calls this before starting its wait logic. The returned receiver is passed to startup and server-wait functions so both can stop promptly if the user cancels.

Call graph: called by 1 (run_foreground_remote_control); 4 external calls (eprintln!, ctrl_c, spawn, channel).

async fn wait_for_foreground_remote_control_start(
    app_server_task: &mut JoinHandle<std::io::Result<()>>,
    ready: impl std::future::Future<Output = anyhow::Result<AppServerRemoteControlReadySta

Purpose: Waits for the foreground app-server to either become ready, fail readiness, exit early, or be cancelled by the user. It turns that race into one clear startup result.

Data flow: It receives the running app-server task, a future that checks remote-control readiness, and a stop-signal receiver. Whichever completes first determines the returned ForegroundStartupResult.

Call relations: run_foreground_remote_control uses this during startup. Tests also call it to confirm that Ctrl-C and early app-server exits are reported correctly.

Call graph: called by 3 (run_foreground_remote_control, foreground_start_wait_reports_app_server_exit_before_ready, foreground_start_wait_stops_before_ready); 2 external calls (pin!, select!).

async fn wait_for_foreground_app_server(
    mut app_server_task: JoinHandle<std::io::Result<()>>,
    mut stop_rx: watch::Receiver<bool>,
) -> anyhow::Result<()>

Purpose: Keeps the foreground command alive while the app-server is running. If the user asks to stop, it aborts the app-server and returns cleanly.

Data flow: It receives the app-server task and the stop-signal receiver. It waits for either the server task to finish or the stop signal to become true; server errors are returned, while user stop causes an abort and then success.

Call relations: run_foreground_remote_control calls this after remote control is ready and the ready message has been printed. A test calls it directly to verify that a stop signal ends the wait.

Call graph: called by 2 (run_foreground_remote_control, foreground_wait_aborts_app_server_on_stop_signal); 1 external calls (select!).

async fn wait_for_stop_signal(stop_rx: &mut watch::Receiver<bool>)

Purpose: Waits until the shared stop flag says the user has requested shutdown. It also returns immediately if the flag was already set.

Data flow: It reads the current boolean value from a watch receiver. If it is false, it waits until another task changes it to true; it produces no data, only the timing signal.

Call relations: The foreground startup and foreground running waits use this as their cancellation branch. It is the small adapter that turns the Ctrl-C watcher’s shared value into something async code can wait on.

Call graph: 2 external calls (borrow, wait_for).

fn foreground_app_server_exited_before_ready(
    result: Result<std::io::Result<()>, tokio::task::JoinError>,
) -> anyhow::Error

Purpose: Turns an early app-server exit into a clear error message. This helps distinguish “remote control was not ready yet” from ordinary runtime shutdown.

Data flow: It receives the result of joining the app-server task. It looks at whether the task ended successfully, returned an I/O error, or failed as a task, then wraps that situation in a descriptive error.

Call relations: wait_for_foreground_remote_control_start uses this when the app-server finishes before readiness is confirmed. The result is passed back to run_foreground_remote_control as a startup failure.

Call graph: 2 external calls (anyhow!, new).

async fn abort_foreground_app_server(app_server_task: JoinHandle<std::io::Result<()>>)

Purpose: Stops a foreground app-server task when startup is cancelled or the user requests shutdown. It prevents the command from leaving a stray background task behind.

Data flow: It receives the app-server task handle, asks Tokio to abort it, then waits briefly for that abort to complete. If the task does not finish within the short timeout, the function still returns.

Call relations: run_foreground_remote_control calls this on cancellation, failed readiness, output failure, or stop. wait_for_foreground_app_server also uses the same shutdown idea when Ctrl-C happens during normal foreground running.

Call graph: called by 1 (run_foreground_remote_control); 2 external calls (abort, timeout).

async fn wait_for_foreground_remote_control_ready(
    socket_path: AbsolutePathBuf,
) -> anyhow::Result<AppServerRemoteControlReadyStatus>

Purpose: Connects to the foreground app-server’s private socket and asks it to enable remote control. It waits with retry and timeout settings because the socket may not be ready instantly.

Data flow: It receives an absolute socket path. It passes that path, a maximum wait time, and a retry delay to the daemon helper; the result is a remote-control readiness summary or an error.

Call relations: run_foreground_remote_control gives this future to wait_for_foreground_remote_control_start. It is the bridge between “server process started” and “remote control is actually usable.”

Call graph: calls 1 internal fn (as_path); called by 1 (run_foreground_remote_control); 1 external calls (enable_remote_control_on_socket).

fn print_remote_control_start_output(
    output: &AppServerRemoteControlReadyOutput,
    json: bool,
) -> anyhow::Result<()>

Purpose: Prints the result of starting daemon-backed remote control. It supports both human text and JSON, and it refuses to print a success-like result for unusable remote control.

Data flow: It receives the daemon readiness output and the JSON flag. It first checks that the remote-control status is connected or connecting; then it either serializes a JSON object or prints human lines plus details about the app-server binary used by the daemon.

Call relations: run calls this after asking the daemon to ensure remote control is ready. It uses ensure_remote_control_startable, remote_control_start_human_lines, and daemon_app_server_human_lines to build safe output.

Call graph: calls 3 internal fn (daemon_app_server_human_lines, ensure_remote_control_startable, remote_control_start_human_lines); called by 1 (run); 1 external calls (println!).

fn print_foreground_ready_output(
    summary: &AppServerRemoteControlReadyStatus,
    json: bool,
) -> anyhow::Result<()>

Purpose: Prints the result of foreground remote-control startup. It tells the user the machine is available and, in human mode, reminds them that Ctrl-C stops it.

Data flow: It receives a readiness summary and the JSON flag. In JSON mode it checks the status and prints a serialized foreground result; in human mode it prints formatted lines for the foreground case.

Call relations: run_foreground_remote_control calls this once startup has succeeded. It uses the same safety check and message-building helpers as daemon startup, but with foreground-specific wording.

Call graph: calls 2 internal fn (ensure_remote_control_startable, remote_control_start_human_lines); called by 1 (run_foreground_remote_control); 1 external calls (println!).

fn foreground(summary: &'a AppServerRemoteControlReadyStatus) -> Self

Purpose: Builds the JSON-friendly summary for foreground remote-control startup. It marks the mode as foreground and omits daemon-only details.

Data flow: It reads the readiness status, server name, optional environment ID, and timeout flag from the foreground summary. It returns a serializable struct with those values and no daemon field.

Call relations: print_foreground_ready_output uses this when the user requested JSON. It keeps the JSON shape consistent with daemon output while clearly saying this was a foreground run.

fn daemon(output: &'a AppServerRemoteControlReadyOutput) -> Self

Purpose: Builds the JSON-friendly summary for daemon-backed remote-control startup. It includes both remote-control status and daemon startup details.

Data flow: It reads the remote-control readiness part and the daemon output part from the combined daemon result. It returns a serializable struct marked as daemon mode with the daemon details attached.

Call relations: print_remote_control_start_output uses this when JSON output is requested. It packages the daemon helper’s detailed result into the CLI’s public output format.

fn remote_control_start_human_message(
    output: &AppServerRemoteControlReadyStatus,
) -> anyhow::Result<String>

Purpose: Creates the main human-readable message for a successful or still-connecting remote-control start. It also rejects statuses that should not be presented as usable.

Data flow: It receives a readiness summary, first checks that the status is startable, then turns Connected or Connecting into a sentence that includes the server name. Errored or disabled statuses are blocked before formatting.

Call relations: remote_control_start_human_lines uses this as the first line of human output. It depends on ensure_remote_control_startable so callers do not accidentally print a misleading success message.

Call graph: calls 1 internal fn (ensure_remote_control_startable); 2 external calls (format!, unreachable!).

fn ensure_remote_control_startable(
    output: &AppServerRemoteControlReadyStatus,
) -> anyhow::Result<()>

Purpose: Checks whether a remote-control status is acceptable to report as started. Only connected and still-connecting states pass.

Data flow: It receives a readiness summary. If the status is connected or connecting, it returns success; if the status is errored or disabled, it returns a clear error message naming the server.

Call relations: Start-output functions and the human-message helper call this before formatting results. It is the shared guardrail that keeps both JSON and text output honest.

Call graph: called by 3 (print_foreground_ready_output, print_remote_control_start_output, remote_control_start_human_message); 1 external calls (bail!).

fn remote_control_start_human_lines(
    summary: &AppServerRemoteControlReadyStatus,
    mode: RemoteControlHumanOutputMode,
) -> anyhow::Result<Vec<String>>

Purpose: Builds the human-readable lines shown after remote control starts. Foreground mode gets an extra reminder about how to stop it.

Data flow: It receives a readiness summary and an output mode. It creates the main status sentence, then adds Press Ctrl-C to stop. only for foreground mode, and returns the list of lines.

Call relations: Both foreground and daemon start printers call this. The mode value lets one helper serve both cases without duplicating the status wording.

Call graph: called by 2 (print_foreground_ready_output, print_remote_control_start_output); 1 external calls (vec!).

fn daemon_app_server_human_lines(output: &AppServerRemoteControlStartOutput) -> Vec<String>

Purpose: Builds the human-readable lines that say which app-server executable the daemon used. This helps users understand what binary and version are actually running.

Data flow: It receives daemon startup output, extracts the managed Codex path and optional version, and returns three display lines: a heading, the path, and the version or unknown.

Call relations: print_remote_control_start_output calls this after the remote-control status lines for daemon startup. It relies on daemon_app_server_identity to hide the difference between daemon bootstrap and normal daemon start results.

Call graph: calls 1 internal fn (daemon_app_server_identity); called by 1 (print_remote_control_start_output); 1 external calls (vec!).

fn daemon_app_server_identity(
    output: &AppServerRemoteControlStartOutput,
) -> (&std::path::Path, Option<&str>)

Purpose: Extracts the app-server path and version from daemon startup output, no matter which daemon-start path produced it. This gives the display code one simple shape to use.

Data flow: It receives either a bootstrap result or a start result. It matches the variant, then returns a borrowed path and an optional version string from inside that result.

Call relations: daemon_app_server_human_lines calls this before formatting daemon details. It is a small normalizer for the two daemon output variants.

Call graph: called by 1 (daemon_app_server_human_lines).

fn print_remote_control_stop_output(
    output: &AppServerLifecycleOutput,
    json: bool,
) -> anyhow::Result<()>

Purpose: Prints the result of stopping remote control. It supports JSON for scripts and a short sentence for people.

Data flow: It receives lifecycle output from the daemon and the JSON flag. In JSON mode it serializes the full lifecycle output; otherwise it prints the sentence produced by remote_control_stop_human_message.

Call relations: run calls this after it asks the daemon lifecycle system to stop. It is the stop-side counterpart to the start-output functions.

Call graph: called by 1 (run); 1 external calls (println!).

fn remote_control_stop_human_message(output: &AppServerLifecycleOutput) -> String

Purpose: Turns a daemon stop status into a plain English sentence. It gives simple messages for common stop outcomes and a fallback for unusual lifecycle statuses.

Data flow: It receives lifecycle output and reads its status. Stopped becomes Remote control stopped., NotRunning becomes Remote control is not running., and other statuses are included by name in a generic completion message.

Call relations: print_remote_control_stop_output uses this for human output. Keeping it separate makes the wording easy to test and adjust.

Call graph: 1 external calls (format!).

fn remote_control_status(
        status: RemoteControlConnectionStatus,
    ) -> AppServerRemoteControlReadyStatus

Purpose: Creates a sample remote-control readiness status for tests. It avoids repeating the same test data in every assertion.

Data flow: It receives a connection status and builds a readiness summary with a fixed server name, fixed environment ID, and a timeout flag that is true only for the connecting case.

Call relations: Several tests call this to check human and JSON formatting. It is test support code, not part of the production command path.

fn daemon_ready_output(
        status: RemoteControlConnectionStatus,
    ) -> AppServerRemoteControlReadyOutput

Purpose: Creates a sample daemon readiness result for tests. It includes both daemon lifecycle details and remote-control status details.

Data flow: It receives a connection status and builds a full daemon output with fixed paths, versions, process ID, server name, and environment ID. The timeout flag mirrors the connecting status.

Call relations: JSON and daemon display tests use this fixture to verify output without needing a real daemon. It is test-only setup data.

Call graph: 2 external calls (Start, from).

fn remote_control_human_start_messages_use_server_name()

Purpose: Verifies that human start messages include the server name and reject bad statuses. This protects the user-facing wording for connected, connecting, errored, and disabled cases.

Data flow: It builds sample statuses, calls the human-message helper, and compares either the returned sentence or returned error text to the expected value.

Call relations: This test exercises remote_control_start_human_message and, through it, the startability check. It helps ensure users do not see a misleading success message.

Call graph: 1 external calls (assert_eq!).

fn remote_control_human_lines_include_foreground_stop_hint_only()

Purpose: Verifies that only foreground mode prints the Ctrl-C stop hint. Daemon mode should not tell the user to press Ctrl-C because the daemon continues after the command exits.

Data flow: It creates a connected status, asks for foreground lines and daemon lines, and compares each list to the expected text.

Call relations: This test calls remote_control_start_human_lines using sample status data. It protects the difference between foreground and daemon user instructions.

Call graph: 2 external calls (assert_eq!, remote_control_status).

fn daemon_app_server_human_lines_include_path_and_version()

Purpose: Verifies that daemon human output includes the app-server path and version. This keeps diagnostic information visible to users.

Data flow: It creates a daemon output fixture, passes its daemon section to the formatting helper, and compares the resulting lines to the expected path and version text.

Call relations: This test covers daemon_app_server_human_lines and indirectly the identity extraction helper. It does not start a real daemon.

Call graph: 1 external calls (assert_eq!).

fn remote_control_json_output_marks_foreground_or_daemon()

Purpose: Verifies the JSON shape for both foreground and daemon startup output. It makes sure tools can tell which mode was used and can read the expected fields.

Data flow: It builds foreground and daemon sample outputs, converts the JSON-output structs to JSON values, and compares them to exact expected JSON objects.

Call relations: This test exercises RemoteControlStartJsonOutput::foreground and RemoteControlStartJsonOutput::daemon. It protects the machine-readable contract of the CLI.

Call graph: 3 external calls (assert_eq!, daemon_ready_output, remote_control_status).

fn remote_control_daemon_json_rejects_unstartable_status()

Purpose: Verifies that daemon JSON output is not printed for an errored remote-control status. This confirms JSON mode follows the same safety rule as human mode.

Data flow: It creates a daemon output whose remote-control status is errored, calls the daemon start printer in JSON mode, and checks that the returned error message is correct.

Call relations: This test covers print_remote_control_start_output and the shared startability check. It guards against scripts receiving a success-shaped JSON object for a failed connection.

Call graph: 1 external calls (assert_eq!).

async fn foreground_wait_aborts_app_server_on_stop_signal()

Purpose: Verifies that the foreground wait ends cleanly when a stop signal is already set. This simulates the user pressing Ctrl-C while the app-server task would otherwise run forever.

Data flow: It starts a never-ending app-server task, creates a stop channel, sets the stop value to true, then calls wait_for_foreground_app_server inside a timeout. The expected result is a clean return before the timeout expires.

Call relations: This async test calls wait_for_foreground_app_server directly. It protects the shutdown path used by foreground remote control.

Call graph: calls 1 internal fn (wait_for_foreground_app_server); 4 external calls (from_secs, spawn, channel, timeout).

async fn foreground_start_wait_stops_before_ready()

Purpose: Verifies that foreground startup returns a stopped result if the stop signal arrives before readiness. This covers cancelling startup before the server is usable.

Data flow: It starts a never-ending app-server task, creates and sets a stop signal, and waits for startup using a readiness future that never completes. The expected startup result is Stopped.

Call relations: This async test calls wait_for_foreground_remote_control_start. It mirrors the early-cancel branch used by run_foreground_remote_control.

Call graph: calls 1 internal fn (wait_for_foreground_remote_control_start); 5 external calls (assert!, from_secs, spawn, channel, timeout).

async fn foreground_start_wait_reports_app_server_exit_before_ready()

Purpose: Verifies that startup reports a useful error if the app-server exits before remote control becomes ready. This helps users see that startup failed early instead of silently hanging.

Data flow: It starts an app-server task that immediately returns an I/O error, uses a readiness future that never completes, and waits for startup. It expects an AppServerExited result with the specific early-exit message.

Call relations: This async test calls wait_for_foreground_remote_control_start and checks the error path produced through foreground_app_server_exited_before_ready. It protects the failure reporting used during foreground startup.

Call graph: calls 1 internal fn (wait_for_foreground_remote_control_start); 7 external calls (assert_eq!, other, panic!, from_secs, spawn, channel, timeout).

async fn run_command_under_seatbelt(
    _command: SeatbeltCommand,
    _codex_linux_sandbox_exe: Option<PathBuf>,
    _loader_overrides: LoaderOverrides,
) -> anyhow::Result<()>

Purpose: Starts a command under the macOS Seatbelt sandbox, which is Apple's built-in process restriction system. On non-macOS systems, it reports that this sandbox is not available.

Data flow: It receives a parsed Seatbelt command, an optional path to the Linux sandbox helper, and configuration loading overrides. On macOS, it pulls out the permission profile, working directory, denial logging choice, Unix socket allowances, and command arguments, decides whether managed requirements should count, then passes the full request to the shared sandbox runner. The result is either a completed sandboxed run or an error.

Call relations: This is the macOS-specific front door into the shared sandbox flow. It uses ManagedRequirementsMode::for_profile_invocation to interpret the user's profile choice, then hands off to run_command_under_sandbox; if compiled on another operating system, it stops immediately with an error.

Call graph: calls 2 internal fn (for_profile_invocation, run_command_under_sandbox); 1 external calls (bail!).

async fn run_command_under_landlock(
    command: LandlockCommand,
    codex_linux_sandbox_exe: Option<PathBuf>,
    loader_overrides: LoaderOverrides,
) -> anyhow::Result<()>

Purpose: Starts a command under the Linux Landlock sandbox, which limits what files and resources the process can access. It prepares the Linux-specific request and delegates the rest to the common runner.

Data flow: It receives a parsed Landlock command, an optional sandbox helper executable path, and configuration loader overrides. It extracts the permission profile, working directory, CLI config overrides, and command to run, chooses whether managed requirements apply, and passes those values into the shared sandbox runner. The output is the final result of running or failing to run the sandboxed command.

Call relations: This is the Linux-oriented entry into the shared sandbox machinery. It calls ManagedRequirementsMode::for_profile_invocation first, then relies on run_command_under_sandbox to load configuration, create sandbox arguments, spawn the child process, and report the exit status.

Call graph: calls 2 internal fn (for_profile_invocation, run_command_under_sandbox).

async fn run_command_under_windows_sandbox(
    command: WindowsCommand,
    codex_linux_sandbox_exe: Option<PathBuf>,
    loader_overrides: LoaderOverrides,
) -> anyhow::Result<()>

Purpose: Starts a command under the Windows sandbox path. It packages the Windows command settings and sends them through the shared sandbox runner.

Data flow: It receives a parsed Windows sandbox command, an optional Linux sandbox helper path, and loader overrides. It extracts the requested permission profile, working directory, command, and config overrides, decides whether managed requirements should be included, and calls the shared runner with the Windows sandbox type. The caller gets success only if the command runs and exits cleanly according to the shared exit handling.

Call relations: This is the Windows-specific front door. Like the macOS and Linux entry functions, it first calls ManagedRequirementsMode::for_profile_invocation, then passes control to run_command_under_sandbox, which branches into Windows-only session launching when appropriate.

Call graph: calls 2 internal fn (for_profile_invocation, run_command_under_sandbox).

fn for_profile_invocation(
        permissions_profile: &Option<String>,
        include_managed_config: bool,
    ) -> Self

Purpose: Decides whether managed requirements, such as centrally supplied permission rules, should be included for this sandbox run. It protects the meaning of an explicit permission profile: if the caller chooses a profile and does not ask to include managed config, managed requirements are ignored.

Data flow: It receives the optional permission profile name and a boolean saying whether managed configuration should be included. If there is a profile and managed config was not requested, it returns Ignore; otherwise it returns Include. Nothing outside the return value is changed.

Call relations: The three platform entry functions call this before entering the common runner. The returned mode later influences configuration loading inside build_debug_sandbox_config_with_loader_overrides, where managed requirements may be turned off.

Call graph: called by 3 (run_command_under_landlock, run_command_under_seatbelt, run_command_under_windows_sandbox).

async fn run_command_under_sandbox(
    config_options: DebugSandboxConfigOptions,
    command: Vec<String>,
    config_overrides: CliConfigOverrides,
    codex_linux_sandbox_exe: Option<PathBuf>,

Purpose: This is the main coordinator that turns a sandbox debug request into a real child process running with restricted permissions. It loads configuration, prepares environment variables and network proxy settings, builds platform-specific sandbox arguments, starts the process, optionally reports denials, and handles the exit status.

Data flow: It receives config options, the command to run, CLI config overrides, an optional Linux sandbox helper path, the sandbox type, denial logging settings, and extra allowed Unix sockets. It loads the effective Codex configuration, chooses the working directory, builds the child environment, optionally starts a managed network proxy, adjusts permissions so the proxy certificate can be read, and then spawns the correct sandbox wrapper for macOS or Linux, or starts a Windows sandbox session. It waits for the child process, prints macOS denial information if requested, and exits according to the child's status.

Call relations: All platform entry functions hand off to this shared runner. It calls load_debug_sandbox_config for configuration, uses platform helper functions such as create_seatbelt_command_args or create_linux_sandbox_command_args_for_permission_profile to build sandbox launch arguments, calls spawn_debug_sandbox_child for non-Windows child processes, calls run_command_under_windows_session for Windows, and finally passes the child's exit status to handle_exit_status.

Call graph: calls 9 internal fn (load_debug_sandbox_config, run_command_under_windows_session, spawn_debug_sandbox_child, handle_exit_status, create_env, allow_network_for_proxy, create_linux_sandbox_command_args_for_permission_profile, create_seatbelt_command_args, parse_overrides); called by 3 (run_command_under_landlock, run_command_under_seatbelt, run_command_under_windows_sandbox); 6 external calls (from, bail!, with_managed_mitm_ca_readable_root, eprintln!, default, unreachable!).

async fn run_command_under_windows_session(
    config: &Config,
    command: Vec<String>,
    cwd: AbsolutePathBuf,
    workspace_roots: Vec<AbsolutePathBuf>,
    env: std::collections::HashMap<Strin

Purpose: Starts and drives a Windows sandbox session for the requested command. It is written to end the current process with the sandboxed command's exit code, so it behaves like the sandboxed program inherited the terminal directly.

Data flow: It receives the loaded configuration, command arguments, working directory, workspace roots, and environment variables. It builds a Windows sandbox session request using the effective permission profile, Codex home, sandbox level, terminal settings, and private desktop setting. If the session cannot start, it prints an error and exits with code 1; otherwise it forwards standard input, output, and error until the sandboxed command finishes, then exits with that command's code.

Call relations: run_command_under_sandbox calls this only when the requested sandbox type is Windows and the code is running on Windows. It hands the session to the Windows sandbox library and then to standard-input/output forwarding, rather than returning to the normal child-process path.

Call graph: calls 1 internal fn (as_path); called by 1 (run_command_under_sandbox); 4 external calls (forward_sandbox_session_stdio, eprintln!, from_config, exit).

async fn spawn_debug_sandbox_child(
    program: PathBuf,
    args: Vec<String>,
    arg0: Option<&str>,
    cwd: PathBuf,
    network_sandbox_policy: NetworkSandboxPolicy,
    mut env: std::collectio

Purpose: Starts the actual sandbox wrapper process for non-Windows runs, with the right arguments, working directory, environment, and inherited terminal streams. It is the final launch step before the debug command is running.

Data flow: It receives the wrapper program path, argument list, optional displayed process name, working directory, network policy, a prepared environment map, and a callback that can add more environment variables. It creates a Tokio child process command, clears the parent environment, installs only the chosen variables, marks network-disabled state when needed, connects the child's input/output/error to the current terminal, and spawns it. The result is a running child process handle or an I/O error.

Call relations: run_command_under_sandbox calls this after it has built either Seatbelt or Landlock launch arguments. The returned child handle is then watched by run_command_under_sandbox, which waits for completion and performs any denial logging or exit handling.

Call graph: calls 1 internal fn (is_enabled); called by 1 (run_command_under_sandbox); 2 external calls (inherit, new).

async fn load_debug_sandbox_config(
    cli_overrides: Vec<(String, TomlValue)>,
    codex_linux_sandbox_exe: Option<PathBuf>,
    options: DebugSandboxConfigOptions,
    strict_config: bool,
) -> any

Purpose: Loads the Codex configuration for a debug sandbox run using the normal Codex home location. It is a convenience wrapper around the more flexible config-loading function.

Data flow: It receives parsed CLI overrides, an optional Linux sandbox helper path, debug sandbox options, and a strict-config flag. It forwards those values to load_debug_sandbox_config_with_codex_home with no custom Codex home. It returns the built Config or an error.

Call relations: run_command_under_sandbox calls this at the start of a sandbox run. The heavier logic lives in load_debug_sandbox_config_with_codex_home, which tests also call directly so they can use temporary Codex home folders.

Call graph: calls 1 internal fn (load_debug_sandbox_config_with_codex_home); called by 1 (run_command_under_sandbox).

async fn load_debug_sandbox_config_with_codex_home(
    cli_overrides: Vec<(String, TomlValue)>,
    codex_linux_sandbox_exe: Option<PathBuf>,
    options: DebugSandboxConfigOptions,
    codex_home: O

Purpose: Builds the effective configuration for a debug sandbox run, including compatibility rules for old and new permission settings. It makes sure explicit permission profiles are respected, while older configs still default to a safer read-only sandbox.

Data flow: It receives CLI override key-value pairs, an optional Linux sandbox helper path, debug sandbox options, an optional Codex home directory, and a strict-config flag. If the user selected a permission profile, it adds that as the default_permissions override. It then builds a config once, checks whether it uses the newer permission-profile style or an explicit old sandbox_mode, and returns it if so. If neither is true, it rebuilds with a read-only sandbox mode so legacy behavior remains restrictive.

Call relations: The general loader load_debug_sandbox_config calls this during real sandbox runs, and many tests call it directly to check edge cases. It delegates actual builder setup to build_debug_sandbox_config_with_loader_overrides, and uses cli_overrides_use_legacy_sandbox_mode and config_uses_permission_profiles to decide whether to keep the first config or rebuild it as read-only.

Call graph: calls 3 internal fn (build_debug_sandbox_config_with_loader_overrides, cli_overrides_use_legacy_sandbox_mode, config_uses_permission_profiles); called by 8 (load_debug_sandbox_config, debug_sandbox_defaults_legacy_configs_to_read_only, debug_sandbox_honors_active_permission_profiles, debug_sandbox_honors_config_profile_loader_overrides, debug_sandbox_honors_explicit_builtin_permission_profile, debug_sandbox_honors_explicit_legacy_sandbox_mode, debug_sandbox_honors_explicit_named_permission_profile, debug_sandbox_uses_explicit_cwd); 2 external calls (default, String).

async fn build_debug_sandbox_config_with_loader_overrides(
    cli_overrides: Vec<(String, TomlValue)>,
    harness_overrides: ConfigOverrides,
    codex_home: Option<PathBuf>,
    managed_requirement

Purpose: Creates a Config object from CLI overrides, harness overrides, optional Codex home, loader settings, and the managed-requirements choice. This is the low-level config builder used by the sandbox debug path.

Data flow: It receives override values from the command line and harness, an optional Codex home directory, the managed requirements mode, loader overrides, and a strict-config flag. It sets up a ConfigBuilder, marks managed requirements to be ignored when requested, applies any custom Codex home and fallback working directory, then asynchronously builds the final config. The output is a Config or an I/O error.

Call relations: load_debug_sandbox_config_with_codex_home uses this to build either the first candidate config or the read-only fallback config. Test helpers also call it so tests can compare exact configurations under controlled override combinations.

Call graph: called by 3 (load_debug_sandbox_config_with_codex_home, build_debug_sandbox_config, debug_sandbox_honors_config_profile_loader_overrides); 2 external calls (default, matches!).

fn config_uses_permission_profiles(config: &Config) -> bool

Purpose: Checks whether the effective configuration uses the newer permission-profile setting. This tells the loader not to apply the old read-only fallback behavior.

Data flow: It receives a loaded Config. It looks inside the effective configuration layer for the default_permissions key and returns true if it is present, false otherwise. It does not modify the config.

Call relations: load_debug_sandbox_config_with_codex_home calls this after building a candidate config. If it returns true, the loader keeps that config because a permission profile is already in charge.

Call graph: called by 1 (load_debug_sandbox_config_with_codex_home).

fn cli_overrides_use_legacy_sandbox_mode(cli_overrides: &[(String, TomlValue)]) -> bool

Purpose: Checks whether the caller explicitly supplied the older sandbox_mode override. This preserves the caller's intentional legacy setting instead of silently replacing it with read-only.

Data flow: It receives a list of CLI override pairs. It scans the keys and returns true if any key is exactly sandbox_mode; otherwise it returns false. The override list is only read, not changed.

Call relations: load_debug_sandbox_config_with_codex_home calls this before deciding whether to rebuild the config with a read-only fallback. A true result means the user deliberately chose the older sandbox mode, so the first config is kept.

Call graph: called by 1 (load_debug_sandbox_config_with_codex_home).

async fn build_debug_sandbox_config(
        cli_overrides: Vec<(String, TomlValue)>,
        harness_overrides: ConfigOverrides,
        codex_home: Option<PathBuf>,
        managed_requirements_mode

Purpose: Provides a shorter test-only way to build a debug sandbox config without custom loader overrides. It keeps the tests focused on the behavior they are checking.

Data flow: It receives CLI overrides, harness overrides, optional Codex home, managed requirements mode, and a strict-config flag. It calls build_debug_sandbox_config_with_loader_overrides with default loader overrides and returns the resulting config or error.

Call relations: Several tests use this helper to build comparison configurations. It sits between test cases and the production config builder, reducing repeated setup code.

Call graph: calls 1 internal fn (build_debug_sandbox_config_with_loader_overrides); 1 external calls (default).

fn escape_toml_path(path: &std::path::Path) -> String

Purpose: Formats a filesystem path so it can be safely placed inside a TOML configuration string used by tests. This is especially important on systems where paths contain backslashes.

Data flow: It receives a path, turns it into display text, and doubles backslashes so the TOML text will read it correctly. It returns the escaped string and changes nothing on disk.

Call relations: The test config-writing helper uses this when embedding temporary directory paths into generated config files. It supports the tests that create named permission profiles.

Call graph: 1 external calls (display).

fn write_permissions_profile_config(
        codex_home: &TempDir,
        docs: &std::path::Path,
        private: &std::path::Path,
    ) -> std::io::Result<()>

Purpose: Writes a test Codex config file into a temporary Codex home directory. The config defines a named permission profile with limited file access and network enabled.

Data flow: It receives a temporary Codex home directory plus paths for a readable docs folder and a private folder that should be denied. It chooses the standard config.toml path under Codex home and delegates the actual file creation. The result is success or an I/O error.

Call relations: Tests call this when they need a realistic named permission profile. It delegates to tests::write_permissions_profile_config_to_path, which writes the file contents.

Call graph: 2 external calls (path, write_permissions_profile_config_to_path).

fn write_permissions_profile_config_to_path(
        config_path: &std::path::Path,
        docs: &std::path::Path,
        private: &std::path::Path,
    ) -> std::io::Result<()>

Purpose: Creates the actual test configuration file for a limited-read permission profile. It gives tests a small, concrete policy where some paths are allowed and one private path is denied.

Data flow: It receives the config file path, the docs path, and the private path. It creates the private directory, formats a TOML config string with escaped paths, and writes that text to disk. It returns success or an I/O error.

Call relations: This helper is called by tests::write_permissions_profile_config and directly by the loader-override test. The generated config is then loaded by the production config-loading functions under test.

Call graph: 3 external calls (format!, create_dir_all, write).

async fn debug_sandbox_honors_active_permission_profiles() -> anyhow::Result<()>

Purpose: Verifies that when a config already selects a permission profile, the debug sandbox uses that profile instead of falling back to legacy read-only behavior. This protects newer configuration files from being misread as old ones.

Data flow: The test creates temporary Codex and sandbox directories, writes a named permission profile, builds one config from that profile and another forced read-only legacy config, then loads the debug sandbox config normally. It compares the resulting file permissions to confirm they match the profile config and differ from the legacy read-only config.

Call relations: This test exercises load_debug_sandbox_config_with_codex_home, config_uses_permission_profiles, and the test config helpers. It proves the main loader keeps profile-based configuration as the source of truth.

Call graph: calls 1 internal fn (load_debug_sandbox_config_with_codex_home); 10 external calls (default, new, new, assert!, assert_eq!, assert_ne!, build_debug_sandbox_config, write_permissions_profile_config, default, default).

async fn debug_sandbox_honors_config_profile_loader_overrides() -> anyhow::Result<()>

Purpose: Verifies that loader overrides selecting a specific config file and profile are respected by the debug sandbox. This matters when a caller wants the sandbox to use a non-default configuration profile.

Data flow: The test writes a permission-profile config to a custom file, builds loader overrides pointing at that file and profile name, then compares the loaded debug sandbox config against a config built directly from those overrides. It also compares against a read-only config to ensure the custom profile really changed the policy.

Call relations: This test calls build_debug_sandbox_config_with_loader_overrides and load_debug_sandbox_config_with_codex_home. It checks that the loader override path flows all the way through the debug sandbox config-loading path.

Call graph: calls 3 internal fn (build_debug_sandbox_config_with_loader_overrides, load_debug_sandbox_config_with_codex_home, from_absolute_path); 10 external calls (default, new, new, assert!, assert_eq!, assert_ne!, build_debug_sandbox_config, write_permissions_profile_config_to_path, default, default).

async fn debug_sandbox_honors_explicit_legacy_sandbox_mode() -> anyhow::Result<()>

Purpose: Verifies that an explicit old-style sandbox_mode CLI override is not overwritten by the debug sandbox's read-only fallback. This keeps older callers compatible when they intentionally request a legacy mode.

Data flow: The test creates a temporary Codex home and a CLI override setting sandbox_mode to workspace-write. It builds comparison configs for workspace-write and read-only, then loads the debug sandbox config with the explicit override. It checks that the loaded policy matches the explicit workspace-write result, with a Windows-specific allowance where workspace-write may downgrade when Windows sandboxing is disabled.

Call relations: This test exercises cli_overrides_use_legacy_sandbox_mode through load_debug_sandbox_config_with_codex_home. It confirms the loader keeps deliberate legacy CLI input instead of applying the default read-only compatibility rule.

Call graph: calls 1 internal fn (load_debug_sandbox_config_with_codex_home); 10 external calls (default, new, new, assert_eq!, assert_ne!, cfg!, build_debug_sandbox_config, default, default, vec!).

async fn debug_sandbox_defaults_legacy_configs_to_read_only() -> anyhow::Result<()>

Purpose: Verifies the safety fallback for old-style configs: when no permission profile and no explicit sandbox mode are present, the debug sandbox defaults to read-only. This prevents accidental broad access during debugging.

Data flow: The test creates a temporary Codex home, builds a read-only comparison config, then loads the debug sandbox config with no special overrides. It checks that no permission profile is active and that the resulting file permissions equal the read-only policy.

Call relations: This test calls load_debug_sandbox_config_with_codex_home and the test config builder. It validates the branch in the loader that rebuilds the config with SandboxMode::ReadOnly.

Call graph: calls 1 internal fn (load_debug_sandbox_config_with_codex_home); 7 external calls (default, new, new, assert!, assert_eq!, build_debug_sandbox_config, default).

async fn debug_sandbox_honors_explicit_builtin_permission_profile() -> anyhow::Result<()>

Purpose: Verifies that an explicitly requested built-in permission profile, such as workspace write access, is preserved even when managed requirements are ignored. This ensures direct profile choices work without needing a custom config file.

Data flow: The test loads a debug sandbox config with the built-in :workspace profile and managed requirements set to ignore. It extracts the actual file-system policy and compares it with the expected built-in workspace-write policy, checking that the expected rules are present.

Call relations: This test calls load_debug_sandbox_config_with_codex_home with a direct profile name. It protects the path where load_debug_sandbox_config_with_codex_home converts permissions_profile into a default_permissions override.

Call graph: calls 2 internal fn (load_debug_sandbox_config_with_codex_home, workspace_write); 4 external calls (new, new, assert!, default).

async fn debug_sandbox_honors_explicit_named_permission_profile() -> anyhow::Result<()>

Purpose: Verifies that an explicitly requested named permission profile from the user's config is honored. This checks that choosing a profile by name produces the same policy as setting it in config.

Data flow: The test writes a named limited-read profile into a temporary Codex home, then loads the debug sandbox config with that profile name as the explicit request. It separately builds the expected config by setting default_permissions to the same name, and compares the resulting file-system policies.

Call relations: This test uses the permission-profile config helper, load_debug_sandbox_config_with_codex_home, and the test config builder. It confirms the explicit profile path matches normal config-based profile selection.

Call graph: calls 1 internal fn (load_debug_sandbox_config_with_codex_home); 8 external calls (new, new, assert_eq!, build_debug_sandbox_config, write_permissions_profile_config, default, default, vec!).

async fn debug_sandbox_uses_explicit_cwd() -> anyhow::Result<()>

Purpose: Verifies that an explicit working directory option becomes the working directory in the loaded debug sandbox config. This matters because sandbox rules can depend on where the command is run.

Data flow: The test creates temporary Codex home and working directory folders, then loads the debug sandbox config with the working directory set and a workspace permission profile. It checks that the config's cwd equals the requested directory.

Call relations: This test calls load_debug_sandbox_config_with_codex_home and checks that the cwd value passed through DebugSandboxConfigOptions survives the config-building path.

Call graph: calls 1 internal fn (load_debug_sandbox_config_with_codex_home); 4 external calls (new, new, assert_eq!, default).

fn setup_level(&self) -> anyhow::Result<SandboxSetupLevel>

Purpose: This checks which sandbox setup level the user requested. Right now, the only allowed choice is the elevated Windows sandbox, so it rejects the command unless --elevated was supplied.

Data flow: It reads the parsed command fields from SandboxSetupCommand. If the elevated flag is true, it returns the internal Elevated setup level; if not, it returns an error explaining that --elevated is required.

Call relations: The top-level run function calls this first, before doing any real setup. This keeps unsupported or incomplete setup requests from reaching the provisioning code.

Call graph: called by 1 (run); 1 external calls (bail!).

async fn run(cmd: SandboxSetupCommand) -> anyhow::Result<()>

Purpose: This is the main executor for the sandbox setup command. It decides which setup path to run based on the requested setup level.

Data flow: It receives a parsed SandboxSetupCommand, asks setup_level to turn the flags into a supported setup level, and then sends the command to the matching setup routine. Its output is success or an error from whichever step failed.

Call relations: The wider CLI entry point, cli_main, calls this when it has recognized a sandbox setup command. In the current design it always hands off to run_elevated, because elevated setup is the only supported level.

Call graph: calls 2 internal fn (setup_level, run_elevated); called by 1 (cli_main).

fn parse_setup_command(
    sandbox_command: &[String],
) -> anyhow::Result<Option<SandboxSetupCommand>>

Purpose: This tries to recognize and parse the setup subcommand from raw sandbox command arguments. It lets the broader sandbox CLI tell the difference between setup requests and other sandbox-related commands.

Data flow: It receives a list of argument strings. If the first word is not setup, it returns None to say “this is not my command.” If it is setup, it asks Clap, the command-line parsing library, to convert those strings into a SandboxSetupCommand, returning either that parsed command or a parsing error.

Call relations: The main CLI code calls this while deciding what kind of sandbox command it has received. Two tests also call it directly: one proves it parses setup arguments, and another proves it leaves non-setup arguments alone.

Call graph: called by 3 (cli_main, ignores_non_setup_sandbox_command_args, parses_setup_from_sandbox_command_args); 1 external calls (try_parse_from).

async fn run_elevated(cmd: SandboxSetupCommand) -> anyhow::Result<()>

Purpose: This performs the actual elevated Windows sandbox setup flow. It identifies the target user and Codex home folder, runs the Windows provisioning work, saves the configuration, and prints a success message.

Data flow: It starts with the parsed command. First it calls resolve_sandbox_setup_identity to get the real Windows username and the Codex home path. Then it calls the core Windows sandbox provisioning function with those values. After provisioning succeeds, it updates the Codex configuration in that home folder to say the sandbox mode is elevated. Finally, it prints a confirmation. If provisioning succeeds but saving config fails, it returns an error that makes that partial success clear.

Call relations: run calls this after confirming that the requested setup level is elevated. This function then hands the low-level Windows work to codex_core::windows_sandbox::run_elevated_provisioning_setup and hands the config-writing work to ConfigEditsBuilder.

Call graph: calls 3 internal fn (resolve_sandbox_setup_identity, new, run_elevated_provisioning_setup); called by 1 (run); 1 external calls (println!).

fn resolve_sandbox_setup_identity(
    cmd: &SandboxSetupCommand,
) -> anyhow::Result<SandboxSetupIdentity>

Purpose: This works out which Windows account and which Codex home folder the setup should apply to. It supports both the current user and a separately named managed-deployment user.

Data flow: It reads the parsed command. If --current-user was used, it reads the username from environment variables such as USERNAME or USER, then uses the provided Codex home or discovers the default one. If --user was used, it requires both the username and --codex-home. It returns a small identity object containing the chosen username and path, or an error if required information is missing.

Call relations: run_elevated calls this before provisioning because the core setup code needs exact user and folder information. This function calls find_codex_home only for the current-user case where no home folder was explicitly given.

Call graph: calls 1 internal fn (find_codex_home); called by 1 (run_elevated); 1 external calls (var).

fn parses_managed_user_identity()

Purpose: This test proves that the command-line parser accepts a managed Windows user with an explicit Codex home. It protects the deployment scenario where setup is run for a named account.

Data flow: It feeds sample arguments into the parser: setup, --elevated, --user, and --codex-home. It then checks that the parsed command has the elevated flag set, stores the expected username, does not mark current-user mode, and keeps the expected Codex home path.

Call relations: This test calls the same Clap parsing path used by real CLI input. It supports the behavior that parse_setup_command and run depend on later.

Call graph: 3 external calls (assert!, assert_eq!, try_parse_from).

fn requires_explicit_user_identity()

Purpose: This test proves that the setup command refuses to run unless the user identity is stated. That prevents provisioning from guessing the wrong Windows account.

Data flow: It tries to parse only setup --elevated. The parser returns an error, and the test checks that the error is specifically a missing required argument.

Call relations: This test exercises the command definition rules directly. It backs up the guarantee that resolve_sandbox_setup_identity should receive a command that has either --user or --current-user.

Call graph: 2 external calls (assert_eq!, try_parse_from).

fn requires_codex_home_for_managed_user()

Purpose: This test proves that a named managed user must also provide a Codex home folder. That matters because the program cannot safely infer another user’s Codex configuration location.

Data flow: It tries to parse setup --elevated --user DOMAIN\alice without --codex-home. The parser rejects it, and the test checks that the rejection is a missing required argument.

Call relations: This test confirms the parser-level rule used before run_elevated is reached. It reduces the chance that the provisioning step runs without knowing where to write the user’s Codex configuration.

Call graph: 2 external calls (assert_eq!, try_parse_from).

fn parses_setup_from_sandbox_command_args()

Purpose: This test proves that parse_setup_command recognizes a real setup command and returns the parsed command. It checks the bridge between the wider sandbox CLI and this setup-specific file.

Data flow: It passes a list of strings beginning with setup and including elevated managed-user options. parse_setup_command returns Some(command), and the test checks that the command contains the expected username.

Call relations: This test calls parse_setup_command, the same helper used by cli_main. It confirms that setup arguments are not merely valid in isolation, but are also detected correctly when routed through the sandbox command parser.

Call graph: calls 1 internal fn (parse_setup_command); 1 external calls (assert_eq!).

fn ignores_non_setup_sandbox_command_args()

Purpose: This test proves that this parser does not steal unrelated sandbox commands. If the first argument is not setup, the helper should step aside.

Data flow: It passes arguments like echo hello into parse_setup_command. The helper returns None, and the test checks that no setup command was produced.

Call relations: This test calls parse_setup_command to protect the broader CLI routing behavior. It ensures cli_main can ask this file about setup commands without breaking other sandbox subcommands.

Call graph: calls 1 internal fn (parse_setup_command); 1 external calls (assert!).

fn candidate_count(&self) -> usize

Purpose: Counts how many rollout scan candidates have been recorded so far. This includes good files, malformed file names, and scan errors, because all of them consume space in the scan report.

Data flow: It reads the current RolloutScan lists, adds their lengths together, and returns that total number. It does not change the scan.

Call relations: The scan limit code asks this for the current total before accepting more work. scan_rollout_root also uses it directly before adding another rollout file.

Call graph: called by 2 (reached_candidate_cap, scan_rollout_root).

fn reached_candidate_cap(&self) -> bool

Purpose: Checks whether the rollout scan has reached the maximum number of items it is allowed to inspect or record. This keeps the doctor check from spending too much time or memory on huge directories.

Data flow: It asks candidate_count for the current total, compares that total with the fixed scan cap, and returns true or false. It does not change the scan by itself.

Call relations: The error-recording helpers call this before adding malformed names or scan errors, so they can stop adding more detail once the cap has been reached.

Call graph: calls 1 internal fn (candidate_count); called by 2 (record_malformed_name, record_scan_error).

fn record_malformed_name(&mut self, path: PathBuf)

Purpose: Records a rollout file whose name does not match the expected thread naming pattern. If the scan is already full, it marks the scan as capped instead of storing more paths.

Data flow: It receives a file path. If there is still room, it adds that path to malformed_names and updates the cap flag; if there is no room, it only marks reached_scan_cap as true.

Call relations: scan_rollout_root calls this after thread_id_from_rollout says a file was readable but its name could not be interpreted as a proper rollout name.

Call graph: calls 1 internal fn (reached_candidate_cap); called by 1 (scan_rollout_root).

fn record_scan_error(&mut self, message: String)

Purpose: Records a problem encountered while walking rollout directories or reading rollout files. This lets the doctor report explain that the comparison may be incomplete.

Data flow: It receives an error message. If the scan has room, it stores the message and refreshes the cap flag; if not, it marks that the cap was reached and discards the extra message.

Call relations: scan_rollout_root calls this whenever it cannot read a directory entry, learn a file type, or parse a rollout file well enough to use it.

Call graph: calls 1 internal fn (reached_candidate_cap); called by 1 (scan_rollout_root).

fn active_count(&self) -> usize

Purpose: Counts how many scanned rollout files came from the active sessions area. The doctor report uses this as a quick summary of what was found on disk.

Data flow: It reads the scan’s file list, filters out archived files, and returns the number left. It does not modify anything.

Call relations: thread_inventory_check_for_roots uses this count when building the details shown in the final doctor result.

fn archived_count(&self) -> usize

Purpose: Counts how many scanned rollout files came from the archived sessions area. This helps the report separate active conversations from archived ones.

Data flow: It reads the scan’s file list, keeps only files marked archived, and returns that count. Nothing is changed.

Call relations: thread_inventory_check_for_roots includes this number in the basic scan details before comparing against the database.

async fn thread_inventory_check(config: &Config) -> DoctorCheck

Purpose: Runs the thread inventory doctor check using the normal application configuration. This is the public entry used by the doctor system.

Data flow: It receives a Config, pulls out CODEX_HOME, the SQLite home, and the default model provider, then passes those values into the more general root-based checker. It returns the finished DoctorCheck.

Call relations: The broader doctor framework calls this check. It immediately hands the real work to thread_inventory_check_for_roots so the same logic can also be tested with temporary folders.

Call graph: calls 1 internal fn (thread_inventory_check_for_roots).

async fn thread_inventory_check_for_roots(
    codex_home: &Path,
    sqlite_home: &Path,
    default_provider: &str,
) -> DoctorCheck

Purpose: Coordinates the full comparison between rollout files and the SQLite thread inventory. It builds the final health report for this check.

Data flow: It receives the rollout home folder, the SQLite home folder, and the default provider name. It scans rollout files, finds the state database path, adds summary details, then either reports a missing database, reports a database read error, or compares the scan with database rows and returns a DoctorCheck.

Call relations: thread_inventory_check calls this in normal use, and tests call it directly with fake directories. It delegates scanning to scan_rollout_files, database reading to codex_state, missing-database reporting to missing_state_db_check, and full parity comparison to parity_check_from_scan_and_rows.

Call graph: calls 6 internal fn (new, new, missing_state_db_check, parity_check_from_scan_and_rows, push_samples, scan_rollout_files); called by 3 (thread_inventory_check_ok_when_rollouts_match_db, thread_inventory_check_warns_for_missing_stale_and_mismatched_rows, thread_inventory_check); 4 external calls (read_thread_state_audit_rows, state_db_path, format!, vec!).

fn missing_state_db_check(scan: RolloutScan, details: Vec<String>) -> DoctorCheck

Purpose: Builds the doctor result for the special case where the SQLite state database does not exist. It decides whether that is okay or deserves a warning.

Data flow: It receives the rollout scan and already-built detail lines. If no files or scan problems exist, it returns an OK check. If rollout files or scan trouble exist, it returns a warning with issues and, when useful, a remedy explaining how startup backfill can recreate the database.

Call relations: thread_inventory_check_for_roots calls this only after discovering that the database file is missing. It produces the final DoctorCheck without trying to compare database rows.

Call graph: calls 2 internal fn (new, new); called by 1 (thread_inventory_check_for_roots); 1 external calls (format!).

fn parity_check_from_scan_and_rows(
    codex_home: &Path,
    scan: RolloutScan,
    rows: Vec<ThreadStateAuditRow>,
    mut details: Vec<String>,
) -> DoctorCheck

Purpose: Performs the main “do the two inventories match?” comparison. It turns the raw rollout scan and database rows into counts, samples, warnings, and a final status.

Data flow: It receives CODEX_HOME, the scanned rollout files, the database audit rows, and existing detail text. It normalizes paths, groups rows by rollout path, finds missing rows, stale rows, archive mismatches, duplicate thread ids, duplicate database paths, provider summaries, and source summaries. It returns a DoctorCheck with OK status if nothing is wrong, otherwise a warning with specific issues.

Call relations: thread_inventory_check_for_roots calls this after successfully reading the database. It relies on helpers such as missing_rollout_paths, duplicate_rollout_thread_ids, duplicate_db_paths, path_key, push_path_samples, and push_samples to keep the comparison readable and the report concise.

Call graph: calls 8 internal fn (new, new, duplicate_db_paths, duplicate_rollout_thread_ids, missing_rollout_paths, path_key, push_path_samples, push_samples); called by 1 (thread_inventory_check_for_roots); 3 external calls (new, new, format!).

async fn scan_rollout_files(codex_home: &Path) -> RolloutScan

Purpose: Scans both active and archived rollout folders under CODEX_HOME. It returns one combined scan result that labels each discovered file as active or archived.

Data flow: It receives CODEX_HOME, creates an empty RolloutScan, scans CODEX_HOME/sessions as active, scans CODEX_HOME/archived_sessions as archived, and returns the filled scan.

Call relations: thread_inventory_check_for_roots calls this at the start of the doctor check. It hands each root folder to scan_rollout_root, which does the actual directory walking.

Call graph: calls 1 internal fn (scan_rollout_root); called by 1 (thread_inventory_check_for_roots); 2 external calls (join, default).

async fn scan_rollout_root(root: &Path, archived: bool, scan: &mut RolloutScan)

Purpose: Walks one rollout directory tree and records usable rollout files, malformed names, and scan errors. It is the file-system crawler for this doctor check.

Data flow: It receives a root path, an archived flag, and a mutable scan. It walks directories, ignores non-rollout files, checks the scan cap, reads each rollout’s thread id, then adds a RolloutAuditFile or records the reason the file could not be used.

Call relations: scan_rollout_files calls it once for active sessions and once for archived sessions. It calls is_rollout_file to filter names, thread_id_from_rollout to extract the thread id, path_key to normalize paths for comparison, and the RolloutScan recording helpers when something goes wrong.

Call graph: calls 6 internal fn (candidate_count, record_malformed_name, record_scan_error, is_rollout_file, path_key, thread_id_from_rollout); called by 1 (scan_rollout_files); 3 external calls (format!, read_dir, vec!).

async fn thread_id_from_rollout(path: &Path) -> RolloutThreadId

Purpose: Reads a rollout file and extracts the thread id that should identify that conversation. It also separates unreadable files from files with malformed rollout names.

Data flow: It receives a rollout file path, loads rollout items from the file, rejects empty or unreadable content, then asks the rollout builder to reconstruct metadata from those items. It returns either a thread id, a malformed-name marker, or an unusable-file reason.

Call relations: scan_rollout_root calls this for each candidate rollout file. Its result decides whether the file becomes part of the comparison or is reported as a scan problem.

Call graph: calls 1 internal fn (load_rollout_items); called by 1 (scan_rollout_root); 2 external calls (Unusable, builder_from_items).

fn is_rollout_file(path: &Path) -> bool

Purpose: Checks whether a path looks like a rollout history file. This prevents the scanner from wasting work on unrelated files.

Data flow: It receives a path and checks two simple facts: the extension must be .jsonl, and the file name must start with rollout-. It returns true only when both are true.

Call relations: scan_rollout_root uses this while walking directories, before it tries to parse a file as rollout data.

Call graph: called by 1 (scan_rollout_root); 3 external calls (new, extension, file_name).

fn count_or_skipped(count: usize, complete: bool) -> String

Purpose: Formats a count for the report, or explains that the count was skipped because the scan was incomplete. This avoids presenting unreliable numbers as if they were exact.

Data flow: It receives a number and a true-or-false flag saying whether the scan was complete. It returns the number as text when complete, or the phrase “skipped (scan cap reached)” when not.

Call relations: parity_check_from_scan_and_rows uses this when reporting stale rows and archive mismatches, because those checks are intentionally skipped if the rollout scan hit its cap.

fn path_key(path: &Path) -> PathBuf

Purpose: Creates a normalized version of a path for reliable comparisons. This helps avoid false mismatches caused by different but equivalent path spellings.

Data flow: It receives a path, tries to normalize it with the shared path utility, and returns the normalized path. If normalization fails, it falls back to the original path.

Call relations: scan_rollout_root stores this key for each rollout file. parity_check_from_scan_and_rows uses it to group database rows and compare them with scanned files, and archived_from_rollout_path uses it to decide which root folder a path belongs to.

Call graph: called by 3 (archived_from_rollout_path, parity_check_from_scan_and_rows, scan_rollout_root); 1 external calls (normalize_for_path_comparison).

fn archived_from_rollout_path(codex_home: &Path, path: &Path) -> Option<bool>

Purpose: Infers whether a rollout path represents an archived or active session based on where it lives under CODEX_HOME. It is a fallback when the file was not already found in the scan map.

Data flow: It receives CODEX_HOME and a rollout path. It normalizes the path and compares it with the normalized archived_sessions and sessions roots, returning Some(true), Some(false), or None if the path is outside both known areas.

Call relations: parity_check_from_scan_and_rows uses this during archive mismatch checks when a database row points at a file that exists but was not found in the initial scanned map.

Call graph: calls 1 internal fn (path_key); 1 external calls (join).

fn missing_rollout_paths(
    files: &'a [RolloutAuditFile],
    rows_by_key: &HashMap<PathBuf, Vec<&ThreadStateAuditRow>>,
    archived: bool,
) -> Vec<&'a Path>

Purpose: Finds rollout files that do not have a matching database thread row. It can do this separately for active files and archived files.

Data flow: It receives scanned files, database rows grouped by normalized path, and the archived flag to check. It keeps files with the requested archive state, asks whether each has a matching row with the same path and thread id, and returns the paths that are missing from the database.

Call relations: parity_check_from_scan_and_rows calls it twice: once for active rollout files and once for archived rollout files. It uses has_matching_thread_row to verify both the path and thread id match.

Call graph: called by 1 (parity_check_from_scan_and_rows); 1 external calls (iter).

fn has_matching_thread_row(
    file: &RolloutAuditFile,
    rows_by_key: &HashMap<PathBuf, Vec<&ThreadStateAuditRow>>,
) -> bool

Purpose: Checks whether one scanned rollout file has a corresponding database row with the same normalized path and thread id. This avoids treating a row for the same path but wrong thread as a valid match.

Data flow: It receives one scanned rollout file and the database rows grouped by path. It looks up rows for that file’s key and returns true if any row has the same id as the file’s thread id.

Call relations: missing_rollout_paths uses this helper while building the list of rollout files that are absent from the SQLite inventory.

fn duplicate_rollout_thread_ids(files: &[RolloutAuditFile]) -> Vec<String>

Purpose: Finds thread ids that appear in more than one scanned rollout file. Duplicate ids are suspicious because each thread should have one identity.

Data flow: It receives the scanned files, walks their thread ids, records ids it has seen, collects ids that appear again, sorts them, and returns the duplicate id list.

Call relations: parity_check_from_scan_and_rows calls this to decide whether to add a duplicate-inventory warning and sample duplicate thread ids in the report.

Call graph: called by 1 (parity_check_from_scan_and_rows); 2 external calls (new, iter).

fn duplicate_db_paths(rows_by_key: &HashMap<PathBuf, Vec<&ThreadStateAuditRow>>) -> Vec<PathBuf>

Purpose: Finds rollout paths that appear in more than one database row. A single rollout file should not be represented by multiple thread records.

Data flow: It receives database rows already grouped by normalized path, keeps paths whose row list has more than one entry, sorts those paths, and returns them.

Call relations: parity_check_from_scan_and_rows calls this after grouping database rows, then uses the result in detail counts, samples, and duplicate-entry warnings.

Call graph: called by 1 (parity_check_from_scan_and_rows).

fn source_category(source: &str) -> &'static str

Purpose: Turns a stored session source value into a small, readable category such as cli, vscode, or subagent:review. This makes report summaries useful without exposing every raw source shape.

Data flow: It receives source text from a database row, tries to parse it as a structured SessionSource or as a plain string source, then returns a stable category name. If parsing fails, it returns “unparsable.”

Call relations: parity_check_from_scan_and_rows uses this while summarizing what kinds of sessions are present in the database. The source_category_coarsens_structured_sources test checks important structured cases.

fn count_summary(values: I) -> String

Purpose: Builds a compact frequency summary for repeated text values. It is used to show, for example, how many rows came from each provider or source category.

Data flow: It receives an iterator of values, counts how many times each appears, sorts by most common and then by name, keeps only a limited number of categories, and returns a comma-separated summary string. If there are no values, it returns “none.”

Call relations: parity_check_from_scan_and_rows uses this for model provider and source summaries. The count_summary_caps_distinct_values test calls it directly to confirm that long category lists are capped.

Call graph: called by 1 (count_summary_caps_distinct_values); 2 external calls (new, format!).

fn push_path_samples(
    details: &mut Vec<String>,
    label: &str,
    paths: impl Iterator<Item = &'a Path>,
)

Purpose: Adds a few example paths to the report details. Samples make the warning actionable without dumping every problem path.

Data flow: It receives the details list, a label, and an iterator of paths. It turns each path into display text and passes the first few values to push_samples.

Call relations: parity_check_from_scan_and_rows uses this for missing, stale, mismatched, and duplicate path examples. It is a path-specific wrapper around push_samples.

Call graph: calls 1 internal fn (push_samples); called by 1 (parity_check_from_scan_and_rows); 1 external calls (map).

fn push_samples(details: &mut Vec<String>, label: &str, values: I)

Purpose: Adds a limited number of example values to the report details. This keeps reports short while still showing concrete evidence.

Data flow: It receives the details list, a label, and values that can be turned into text. It takes only the configured sample limit and appends detail lines in the form “label: value.”

Call relations: thread_inventory_check_for_roots uses it for scan errors and malformed file names. parity_check_from_scan_and_rows uses it for duplicate thread id samples, and push_path_samples uses it for path examples.

Call graph: called by 3 (parity_check_from_scan_and_rows, push_path_samples, thread_inventory_check_for_roots); 2 external calls (take, format!).

async fn thread_inventory_check_ok_when_rollouts_match_db()

Purpose: Tests the healthy case where active and archived rollout files both have matching database rows. It proves the check returns OK when the two inventories agree.

Data flow: It creates a temporary fixture, writes one active rollout and one archived rollout, inserts matching thread rows, runs the checker, and asserts that the status and important detail counts show no problems.

Call relations: This test calls thread_inventory_check_for_roots directly with temporary roots. It uses Fixture helpers to create the fake disk and database state, then uses assert_detail to verify the report.

Call graph: calls 1 internal fn (thread_inventory_check_for_roots); 3 external calls (assert_eq!, new, assert_detail).

async fn thread_inventory_check_warns_for_missing_stale_and_mismatched_rows()

Purpose: Tests a broken inventory with three different problems: a rollout missing from the database, a database row pointing at a missing file, and an archive flag mismatch. It proves these cases become warnings, not silent success.

Data flow: It builds a fixture, writes rollout files, inserts only selected database rows with one wrong archive flag and one stale path, runs the checker, and asserts the warning status, issue count, detail counts, and sample output.

Call relations: This test exercises thread_inventory_check_for_roots through realistic temporary files and rows. It depends on Fixture for setup and assert_detail for checking specific report lines.

Call graph: calls 1 internal fn (thread_inventory_check_for_roots); 4 external calls (assert!, assert_eq!, new, assert_detail).

async fn new() -> Self

Purpose: Creates an isolated test environment with temporary Codex and SQLite homes. This lets tests run without touching a real user’s files.

Data flow: It creates two temporary directories, initializes the state runtime in the SQLite directory so the database schema exists, and returns a Fixture holding both directories.

Call relations: The inventory tests call this before writing rollout files or inserting rows. It hands back the controlled homes used by thread_inventory_check_for_roots.

Call graph: calls 1 internal fn (init); 1 external calls (new).

fn write_rollout(&self, archived: bool, timestamp: &str, thread_id: &str) -> PathBuf

Purpose: Writes a small valid rollout file for a test thread. It can place the file in either the active sessions tree or the archived sessions tree.

Data flow: It receives an archived flag, timestamp, and thread id. It chooses the right folder, creates it, builds a session metadata rollout line, serializes it as JSON, writes it to a rollout-*.jsonl file, and returns the path.

Call relations: The tests call this to create the on-disk side of the comparison. The production scanner later reads these files through scan_rollout_root and thread_id_from_rollout.

Call graph: calls 1 internal fn (from_string); 7 external calls (default, path, format!, SessionMeta, to_string, create_dir_all, write).

async fn insert_thread_row(&self, id: &str, rollout_path: &Path, archived: bool)

Purpose: Inserts one thread inventory row into the temporary SQLite database. This creates the database side of the comparison used by tests.

Data flow: It receives a thread id, rollout path, and archived flag. It opens the test state database, inserts a row with fixed test metadata and the requested values, executes the SQL, and closes the connection pool.

Call relations: The tests use this after writing rollout files to create matching, stale, or mismatched database records. thread_inventory_check_for_roots later reads those rows through codex_state.

Call graph: 6 external calls (display, new, new, path, state_db_path, query).

fn assert_detail(check: &DoctorCheck, label: &str, expected: &str)

Purpose: Checks that a DoctorCheck contains a detail line with an expected value. It makes test assertions easier to read.

Data flow: It receives a check, a detail label, and the expected text. It finds a detail starting with the label, extracts the value after the label, and asserts that it matches the expected value.

Call relations: Both main inventory tests call this to verify individual counts in the doctor report without manually searching the details each time.

Call graph: 2 external calls (assert_eq!, format!).

fn source_category_coarsens_structured_sources()

Purpose: Tests that source_category turns both plain and structured session sources into stable summary labels. This protects report output for subagent and CLI sources.

Data flow: It passes representative source strings into source_category and asserts the returned category names. No files or database rows are involved.

Call relations: This test directly covers the source_category helper used by parity_check_from_scan_and_rows when summarizing database rows.

Call graph: 1 external calls (assert_eq!).

fn count_summary_caps_distinct_values()

Purpose: Tests that count_summary limits long summaries and groups the rest into an “other” bucket. This keeps doctor details from becoming too noisy.

Data flow: It passes nine distinct values into count_summary and asserts that only the configured number of categories are shown before the remaining one is summarized as other.

Call relations: This test directly covers count_summary, which parity_check_from_scan_and_rows uses for provider and source summaries.

Call graph: calls 1 internal fn (count_summary); 1 external calls (assert_eq!).

fn new(severity: CheckStatus, cause: impl Into<String>) -> Self

Purpose: Creates a new specific problem found by a doctor check. It records how serious the problem is and the main reason it matters.

Data flow: It receives a severity and a cause message, converts the message into text, and creates an issue with no measured value, expected value, remedy, or fields yet.

Call relations: Individual checks call this when they discover a concrete problem. Follow-up builder methods add extra explanation before the issue is attached to a DoctorCheck.

Call graph: called by 8 (git_check_from_inputs, provider_reachability_check, terminal_check_from_inputs, terminal_size_issues, missing_state_db_check, parity_check_from_scan_and_rows, thread_inventory_check_for_roots, terminal_title_check_from_inputs); 2 external calls (into, new).

fn measured(mut self, measured: impl Into<String>) -> Self

Purpose: Adds what Codex actually observed for an issue. This helps users compare the current state with what should have been present.

Data flow: It takes an existing issue and a measured text value, stores that value on the issue, and returns the updated issue.

Call relations: It is used after DoctorIssue::new while building a detailed issue, usually before adding expected values and remedies.

Call graph: 1 external calls (into).

fn expected(mut self, expected: impl Into<String>) -> Self

Purpose: Adds what Codex expected to see for an issue. This makes the report more useful than just saying something is wrong.

Data flow: It takes an existing issue and expected text, stores it, and returns the updated issue.

Call relations: It fits into the issue-building chain after a problem is created and before the final issue is attached to a check.

Call graph: 1 external calls (into).

fn remedy(mut self, remedy: impl Into<String>) -> Self

Purpose: Adds a suggested fix for a specific issue. This turns the report from a warning into practical guidance.

Data flow: It takes an existing issue and a remedy message, stores that message, and returns the updated issue.

Call relations: Checks use it while constructing issues that should tell the user how to recover.

Call graph: 1 external calls (into).

fn field(mut self, field: impl Into<String>) -> Self

Purpose: Names the setting, environment variable, or report field connected to an issue. This points the user to the exact thing to inspect.

Data flow: It takes an existing issue and one field name, appends that name to the issue's field list, and returns the updated issue.

Call relations: It is usually used at the end of an issue-building chain, before the issue is added to a DoctorCheck.

Call graph: 1 external calls (into).

fn new(
        id: impl Into<String>,
        category: impl Into<String>,
        status: CheckStatus,
        summary: impl Into<String>,
    ) -> Self

Purpose: Creates the basic result for one doctor check. It gives the check an ID, category, status, and short summary.

Data flow: It receives identifying text, a status, and a summary, then creates a check with empty details, no issues, no remediation, and zero duration.

Call relations: Nearly every doctor check starts here, then adds details, issues, or remediation before being returned to the overall report.

Call graph: called by 25 (auth_check, background_server_check, config_check, fallback_state_check, git_check_from_inputs, installation_check, mcp_check_from_servers, network_check, render_human_report_includes_threads_row_in_environment, provider_reachability_check (+15 more)); 2 external calls (into, new).

fn detail(mut self, detail: impl Into<String>) -> Self

Purpose: Adds one explanatory line to a check. Details are the evidence behind the short summary.

Data flow: It takes a check and a detail string, appends the string to the detail list, and returns the updated check.

Call relations: Checks use this while assembling human-readable context about what was found.

Call graph: 1 external calls (into).

fn details(mut self, details: Vec<String>) -> Self

Purpose: Adds several explanatory lines to a check at once. This is useful when a check has already collected a list of facts.

Data flow: It takes a check and a list of detail strings, appends all of them, and returns the updated check.

Call relations: Most larger checks gather details in a temporary list, then attach them through this method before returning.

fn remediation(mut self, remediation: impl Into<String>) -> Self

Purpose: Adds a suggested next step for fixing a failed or suspicious check. It gives the user a clear action instead of only a diagnosis.

Data flow: It takes a check and remediation text, stores that text, and returns the updated check.

Call relations: Checks call this when their status is warning or fail and there is a useful repair suggestion.

Call graph: 1 external calls (into).

fn issue(mut self, issue: DoctorIssue) -> Self

Purpose: Attaches one specific issue to a check. This lets a check report several problems while keeping one overall status.

Data flow: It takes a check and a DoctorIssue, appends the issue to the check, and returns the updated check.

Call relations: Detailed checks, such as terminal checks, build issues separately and then add them to the final check with this method.

async fn run_doctor(
    command: DoctorCommand,
    root_config_overrides: CliConfigOverrides,
    interactive: &TuiCli,
    arg0_paths: &Arg0DispatchPaths,
) -> anyhow::Result<()>

Purpose: Runs the doctor command from the command line. It builds the report, prints it in the requested format, and exits with an error code if something failed.

Data flow: It receives command options, config overrides, interactive CLI settings, and executable paths. It builds a report, prints either redacted JSON or human text, and returns success unless the report has a failing status, in which case the process exits with code 1.

Call relations: The main CLI calls this when the user asks for codex doctor. It hands the real inspection work to build_report, then chooses the output path.

Call graph: calls 1 internal fn (build_report); called by 1 (cli_main); 3 external calls (print!, println!, exit).

async fn build_report(
    command: &DoctorCommand,
    root_config_overrides: CliConfigOverrides,
    interactive: &TuiCli,
    arg0_paths: &Arg0DispatchPaths,
) -> DoctorReport

Purpose: Coordinates all doctor checks and combines them into one report. It decides which checks can run immediately, which need loaded config, and what fallback checks to run if config loading fails.

Data flow: It receives doctor options, CLI config overrides, interactive settings, and executable paths. It runs system, installation, runtime, search, config-dependent, and fallback checks, records progress, computes the overall status, and returns a complete DoctorReport.

Call relations: run_doctor calls this once. It is the central dispatcher that calls the individual check functions and wraps them with timing and progress helpers.

Call graph: calls 8 internal fn (default_reachability_plan, generated_at, load_config, overall_status, doctor_progress, provider_reachability_plan, run_sync_check, shared_from_config); called by 1 (run_doctor); 3 external calls (new, env!, join!).

async fn load_config(
    root_config_overrides: CliConfigOverrides,
    interactive: &TuiCli,
    arg0_paths: &Arg0DispatchPaths,
) -> anyhow::Result<Config>

Purpose: Loads Codex configuration in the same spirit as a real run, but marked as temporary for doctor inspection. This lets doctor checks see what Codex would actually use.

Data flow: It receives root CLI overrides, interactive options, and executable paths. It parses command-line key-value overrides, adds web search if requested, builds config overrides from interactive flags, and returns a loaded Config or an error.

Call relations: build_report calls this before running checks that need configuration. If it fails, build_report switches to a smaller fallback set of checks.

Call graph: calls 2 internal fn (config_overrides_from_interactive, parse_overrides); called by 1 (build_report); 2 external calls (default, String).

fn config_overrides_from_interactive(
    interactive: &TuiCli,
    arg0_paths: &Arg0DispatchPaths,
) -> ConfigOverrides

Purpose: Turns interactive CLI flags into configuration override values. This keeps the doctor check aligned with the options the user supplied.

Data flow: It reads fields such as model, approval policy, sandbox mode, current directory, OSS provider, executable paths, and writable roots, then returns a ConfigOverrides structure.

Call relations: load_config uses this while preparing the config builder. Tests also use it to ensure important global options are preserved.

Call graph: called by 2 (load_config, config_overrides_from_interactive_preserves_global_options); 1 external calls (default).

fn push(&mut self, value: String)

Purpose: Adds another value to a JSON detail entry that may have one value or many. This keeps repeated detail keys from overwriting each other.

Data flow: It receives a string. If the entry held one previous value, it changes into a list containing the old and new values; if it was already a list, it appends the new value.

Call relations: Structured JSON detail building uses this when several report lines share the same key.

Call graph: 2 external calls (Many, vec!).

fn redacted_json_report(report: &DoctorReport) -> JsonDoctorReport

Purpose: Converts the full doctor report into a JSON-safe version. It keeps useful structure while preparing the data for sharing.

Data flow: It reads the report metadata and checks, converts each check through the redaction path, and returns a JsonDoctorReport keyed by check ID.

Call relations: run_doctor uses this when the user requests JSON output. Tests verify that the resulting structure is sanitized.

Call graph: called by 1 (redacted_json_report_structures_and_sanitizes_details).

fn redacted_json_check(check: &DoctorCheck) -> JsonDoctorCheck

Purpose: Converts one doctor check into its redacted JSON form. It organizes detail lines and removes sensitive text where needed.

Data flow: It reads a DoctorCheck, splits details into structured key-value data and notes, redacts issues and remediation, and returns a JSON check object.

Call relations: redacted_json_report calls this for every check in the report. It delegates detail parsing to structured_json_details.

Call graph: calls 1 internal fn (structured_json_details).

fn redacted_json_issue(issue: &DoctorIssue) -> JsonDoctorIssue

Purpose: Converts one issue into a JSON-safe issue. It redacts every user-facing text field that might contain private local information.

Data flow: It reads severity, cause, measured value, expected value, remedy, and fields from an issue, redacts the text values, and returns a JSON issue.

Call relations: redacted_json_check calls this while preparing the JSON version of a check.

Call graph: calls 1 internal fn (redact_detail).

fn structured_json_details(details: &[String]) -> (BTreeMap<String, JsonDetailValue>, Vec<String>)

Purpose: Turns plain detail lines into structured JSON when they look like key: value. Lines that do not fit that shape become notes.

Data flow: It receives detail strings, redacts each one, splits key-value lines, groups repeated keys, and returns both a map of structured details and a list of free-form notes.

Call relations: redacted_json_check uses this so JSON consumers can read important details by key instead of parsing plain text.

Call graph: calls 2 internal fn (json_detail_value, redact_detail); called by 1 (redacted_json_check); 3 external calls (new, new, One).

fn json_detail_value(key: &str, value: &str) -> String

Purpose: Sanitizes certain detail values before they enter JSON. Editor and pager settings can contain private commands, so JSON only says whether they are set.

Data flow: It receives a detail key and value. For sensitive editor or pager keys, it returns set unless the value says not set; otherwise it returns the original value.

Call relations: structured_json_details calls this while building redacted JSON details.

Call graph: called by 1 (structured_json_details); 1 external calls (matches!).