TUI startup, onboarding, and terminal ownership

async fn start_embedded_app_server(
    arg0_paths: Arg0DispatchPaths,
    config: Config,
    cli_kv_overrides: Vec<(String, toml::Value)>,
    loader_overrides: LoaderOverrides,
    strict_config: b

Purpose: Starts an app server inside the same process as the TUI. This is used when Codex is not connecting to an already-running local or remote server.

Data flow: It receives launch paths, configuration, command-line overrides, cloud config loading, feedback/logging hooks, database handles, and an environment manager. It passes all of that into the more general startup helper and returns an in-process app server client.

Call relations: When start_app_server decides the target is embedded, it calls this wrapper. Tests also call it through start_test_embedded_app_server to create a real embedded server.

Call graph: calls 1 internal fn (start_embedded_app_server_with); called by 2 (start_app_server, start_test_embedded_app_server).

fn uses_remote_workspace(&self) -> bool

Purpose: Answers whether the chosen app server points at a remote workspace rather than the local machine. Many startup choices depend on this because local paths and permissions may not apply remotely.

Data flow: It reads the target variant. If the target is Remote, it returns true; otherwise it returns false.

Call relations: Other startup helpers ask this before deciding thread parameter style, whether to canonicalize a local current directory, whether to load local configured environments, and how run_ratatui_app should behave.

Call graph: called by 4 (thread_params_mode, config_cwd_for_app_server_target, run_ratatui_app, should_load_configured_environments); 1 external calls (matches!).

fn thread_params_mode(&self) -> ThreadParamsMode

Purpose: Chooses the session parameter style expected by the app server. Remote workspaces use remote-style thread parameters; embedded and local daemon modes use embedded-style parameters.

Data flow: It checks whether the target uses a remote workspace and maps that answer to a ThreadParamsMode value.

Call relations: Session creation uses this when wrapping an app server client in AppServerSession, both during normal TUI startup and when temporary sessions are created for pickers.

Call graph: calls 1 internal fn (uses_remote_workspace); called by 2 (run_ratatui_app, start_app_server_for_picker).

async fn init_state_db_for_app_server_target(
    config: &Config,
    app_server_target: &AppServerTarget,
) -> std::io::Result<Option<StateDbHandle>>

Purpose: Opens or finds the local state database used for saved session metadata and rollout state. It treats embedded startup more strictly because the embedded server depends on a working local database.

Data flow: It receives the loaded config and the chosen server target. For embedded mode it tries to initialize the database and turns failures into a typed startup error; for daemon or remote modes it asks for an existing database handle if available.

Call relations: Main startup calls this before launching the app server. Tests use it to verify both normal embedded startup and database failure reporting.

Call graph: calls 2 internal fn (get_state_db, try_init); called by 5 (run_main, start_embedded_app_server_for_picker, embedded_state_db_corruption_preserves_failed_database_for_cli_recovery, embedded_state_db_failure_is_typed_for_cli_recovery, start_test_embedded_app_server).

fn remove_legacy_tui_log_file(codex_home: &Path)

Purpose: Deletes an old shared TUI log file that could otherwise grow forever. The cleanup is best-effort, so startup continues even if the file cannot be removed.

Data flow: It receives the Codex home directory, builds the old log file path, and attempts to remove it without returning an error.

Call relations: Normal startup calls it after config load. A test checks that the legacy file is removed when present.

Call graph: called by 2 (run_main, startup_removes_legacy_tui_log_file); 2 external calls (join, remove_file).

fn remote_addr_has_explicit_port(addr: &str, parsed: &Url) -> bool

Purpose: Checks whether a WebSocket address explicitly includes a port, even when the port is the scheme’s default. Codex requires the port to be written so remote addresses are unambiguous.

Data flow: It receives the original address string and its parsed URL. It inspects the host, scheme, and authority text and returns true only when a port is visibly present.

Call relations: Remote address parsing calls this before accepting ws:// or wss:// endpoints.

Call graph: called by 1 (resolve_remote_addr); 4 external calls (host_str, port, scheme, format!).

fn websocket_url_supports_auth_token(parsed: &Url) -> bool

Purpose: Decides whether it is safe to attach an authentication token to a WebSocket endpoint. Tokens are allowed for secure WebSockets, and for plain WebSockets only when they stay on localhost.

Data flow: It receives a parsed URL, checks its scheme and host, and returns a yes-or-no answer.

Call relations: This is the safety rule behind remote_addr_supports_auth_token.

Call graph: 2 external calls (host, scheme).

fn resolve_remote_addr(addr: &str) -> color_eyre::Result<RemoteAppServerEndpoint>

Purpose: Turns a user-supplied remote address string into the endpoint type the app server client understands. It accepts WebSocket URLs and Unix socket paths, and rejects loose or incomplete addresses.

Data flow: It reads an address string. unix:// becomes the default Codex socket, unix://PATH becomes an absolute socket path, and valid ws://host:port or wss://host:port becomes a WebSocket endpoint; invalid input produces a clear error.

Call relations: The CLI layer can use this before calling run_main with an explicit remote endpoint. Tests exercise valid and invalid forms.

Call graph: calls 2 internal fn (remote_addr_has_explicit_port, relative_to_current_dir); called by 1 (resolve_remote_addr_rejects_invalid_remote_addresses); 5 external calls (parse, app_server_control_socket_path, find_codex_home, bail!, matches!).

fn remote_addr_supports_auth_token(endpoint: &RemoteAppServerEndpoint) -> bool

Purpose: Reports whether an already-resolved remote endpoint may safely carry an auth token. This prevents tokens from being sent over unsafe network paths.

Data flow: It receives a remote endpoint. For WebSockets it parses the stored URL and applies the token-safety rule; for Unix sockets it returns false.

Call relations: It builds on the WebSocket safety helper and is available to callers that need to decide whether token-based connection setup is allowed.

Call graph: 1 external calls (parse).

async fn connect_remote_app_server(
    endpoint: RemoteAppServerEndpoint,
) -> color_eyre::Result<AppServerClient>

Purpose: Connects the TUI to an app server that is already running elsewhere. This is used for explicit remote connections and reusable local daemons.

Data flow: It receives an endpoint, builds connection arguments such as client name, version, API mode, and channel size, then returns a remote app server client wrapped in the common client enum.

Call relations: When start_app_server sees a local daemon or remote target, it delegates the connection work here.

Call graph: calls 1 internal fn (connect); called by 1 (start_app_server); 3 external calls (new, Remote, env!).

async fn maybe_probe_default_daemon_socket(_codex_home: &Path) -> Option<AbsolutePathBuf>

Purpose: Looks for a default local app-server daemon socket and quickly tests whether it is alive. This lets startup reuse a daemon only when doing so is safe and fast.

Data flow: It receives Codex home, computes the standard socket path, checks whether it exists, then attempts a short connection. Success returns the socket path; missing, failed, or timed-out probes return none.

Call relations: On startup, run_main calls this only when the current launch has no special overrides that a daemon could not reproduce.

Call graph: calls 1 internal fn (connect); called by 1 (run_main); 3 external calls (app_server_control_socket_path, timeout, debug!).

async fn start_app_server(
    target: &AppServerTarget,
    arg0_paths: Arg0DispatchPaths,
    config: Config,
    cli_kv_overrides: Vec<(String, toml::Value)>,
    loader_overrides: LoaderOverrides,

Purpose: Starts or connects to the app server selected for this launch. It hides the difference between embedded, local daemon, and remote server modes from later code.

Data flow: It receives the target plus all startup inputs needed by embedded mode. Embedded mode starts an in-process server; daemon and remote modes connect to the endpoint; all paths return a common app server client.

Call relations: Both the main TUI startup and picker-only helpers call this before creating an AppServerSession.

Call graph: calls 2 internal fn (connect_remote_app_server, start_embedded_app_server); called by 2 (run_ratatui_app, start_app_server_for_picker).

async fn start_app_server_for_picker(
    config: &Config,
    target: &AppServerTarget,
    state_db: Option<StateDbHandle>,
    environment_manager: Arc<EnvironmentManager>,
) -> color_eyre::Result<

Purpose: Creates a minimal app server session for resume or fork picker screens. It avoids the full normal startup path while still giving the picker access to saved threads.

Data flow: It receives config, a target, optional state database handle, and an environment manager. It starts the app server with default or empty launch settings, then wraps the client as an AppServerSession.

Call relations: The test-only embedded picker helper calls this after preparing state database and environment objects.

Call graph: calls 5 internal fn (default, new, thread_params_mode, new, start_app_server); called by 1 (start_embedded_app_server_for_picker); 4 external calls (new, clone, default, default).

async fn start_embedded_app_server_for_picker(
    config: &Config,
) -> color_eyre::Result<AppServerSession>

Purpose: Test helper that starts an embedded app server session suitable for picker-related tests. It uses test defaults so tests do not need the full production launch setup.

Data flow: It receives config, initializes the embedded state database, creates a test environment manager, and returns an app server session.

Call relations: It composes the database initializer with start_app_server_for_picker for test use.

Call graph: calls 3 internal fn (default_for_tests, init_state_db_for_app_server_target, start_app_server_for_picker); 1 external calls (new).

async fn start_embedded_app_server_with(
    arg0_paths: Arg0DispatchPaths,
    config: Config,
    cli_kv_overrides: Vec<(String, toml::Value)>,
    loader_overrides: LoaderOverrides,
    strict_conf

Purpose: Builds the full argument package needed to start an embedded app server. It exists so production code and tests can share the same setup while tests can inject a fake starter.

Data flow: It receives config and all launch services, converts startup warnings into protocol notifications, fills client identity and channel settings, calls the supplied starter function, and returns the started in-process client or a contextual error.

Call relations: start_embedded_app_server uses it with the real client starter. A test uses it with a failing starter to verify that startup errors are reported clearly.

Call graph: called by 2 (start_embedded_app_server, embedded_app_server_start_failure_is_returned); 5 external calls (new, new, env!, from_value, json!).

async fn shutdown_app_server_if_present(app_server: Option<AppServerSession>)

Purpose: Shuts down a temporary app server session if one exists. It prevents early-exit paths from leaving background work running.

Data flow: It receives an optional session. If present, it asks the session to shut down and logs a warning if that fails.

Call relations: run_ratatui_app uses this on early exits from onboarding or failed resume/fork lookups.

Call graph: called by 1 (run_ratatui_app); 1 external calls (warn!).

fn session_target_from_app_server_thread(
    thread: AppServerThread,
) -> Option<resume_picker::SessionTarget>

Purpose: Converts a thread returned by the app server into the smaller resume/fork target used by the TUI picker. It filters out threads with invalid IDs.

Data flow: It receives an app-server thread, parses its string ID, and returns a target containing the thread path and typed ID. If parsing fails, it logs a warning and returns none.

Call relations: Session lookup helpers use this after thread/list or thread/read responses.

Call graph: calls 1 internal fn (from_string); called by 2 (lookup_session_target_by_name_with_app_server, lookup_session_target_with_app_server); 1 external calls (warn!).

fn resume_source_kinds(include_non_interactive: bool) -> Vec<ThreadSourceKind>

Purpose: Chooses which kinds of saved sessions should be considered resumable. Interactive sessions are always included, and non-interactive sessions can be added on request.

Data flow: It receives a boolean. It starts with CLI and VS Code sources, then adds Exec and AppServer sources if non-interactive sessions are allowed.

Call relations: latest_session_lookup_params uses this when building app-server list requests.

Call graph: called by 1 (latest_session_lookup_params); 1 external calls (vec!).

async fn lookup_session_target_by_name_with_app_server(
    app_server: &mut AppServerSession,
    name: &str,
) -> color_eyre::Result<Option<resume_picker::SessionTarget>>

Purpose: Finds a saved session whose title exactly matches a given name. This lets users resume or fork by session name rather than ID.

Data flow: It receives a mutable app server session and a name. It pages through search results from the app server, looks for an exact title match, converts the matching thread to a target, and returns none if no page matches.

Call relations: lookup_session_target_with_app_server calls this when the user input is not a UUID. A test verifies that backend title search is used.

Call graph: calls 2 internal fn (thread_list, session_target_from_app_server_thread); called by 2 (lookup_session_target_with_app_server, lookup_session_target_by_name_uses_backend_title_search); 1 external calls (vec!).

async fn lookup_session_target_with_app_server(
    app_server: &mut AppServerSession,
    id_or_name: &str,
) -> color_eyre::Result<Option<resume_picker::SessionTarget>>

Purpose: Finds a saved session by either ID or name. It supports the user-facing --resume <id-or-name> and --fork <id-or-name> behavior.

Data flow: It receives an app server session and a string. If the string looks like a UUID, it reads that thread directly; otherwise it searches by name. It returns a resume/fork target or none.

Call relations: run_ratatui_app calls this when CLI arguments name a specific session.

Call graph: calls 4 internal fn (from_string, thread_read, lookup_session_target_by_name_with_app_server, session_target_from_app_server_thread); called by 1 (run_ratatui_app); 2 external calls (parse_str, warn!).

async fn lookup_latest_session_target_with_app_server(
    app_server: &mut AppServerSession,
    config: &Config,
    cwd_filter: Option<&Path>,
    include_non_interactive: bool,
) -> color_eyre::Re

Purpose: Finds the most recently updated saved session that matches the current scope. It first uses fast database metadata, then falls back to a scan-and-repair path if needed.

Data flow: It receives the app server, config, optional current-directory filter, and whether non-interactive sessions count. It asks the server for one latest thread in two modes and returns the first valid target whose path still makes sense locally or is remote.

Call relations: run_ratatui_app uses this for --resume --last and --fork --last. Tests cover current-directory filtering and fallback behavior.

Call graph: calls 3 internal fn (thread_list, uses_remote_workspace, latest_session_lookup_params); called by 3 (run_ratatui_app, fork_last_filters_latest_session_by_cwd_unless_show_all, latest_session_lookup_falls_back_for_rollout_missing_from_state_db).

fn latest_session_lookup_params(
    uses_remote_workspace: bool,
    config: &Config,
    cwd_filter: Option<&Path>,
    include_non_interactive: bool,
    lookup_mode: LatestSessionLookupMode,
) ->

Purpose: Builds the request sent to the app server when looking for the latest saved session. It keeps local and remote lookup rules separate.

Data flow: It receives remote/local status, config, optional directory filter, source inclusion choice, and lookup mode. It returns a ThreadListParams object with limit, sorting, provider filter, directory filter, and database-only flag set.

Call relations: The latest-session lookup helper calls this for each lookup mode. Tests verify the exact filters for embedded, local daemon, and remote cases.

Call graph: calls 1 internal fn (resume_source_kinds); called by 6 (lookup_latest_session_target_with_app_server, latest_session_lookup_params_can_include_non_interactive_sources, latest_session_lookup_params_keep_explicit_cwd_filter_for_remote_sessions, latest_session_lookup_params_keep_local_filters_for_embedded_sessions, latest_session_lookup_params_keep_local_filters_for_local_daemon_sessions, latest_session_lookup_params_omit_local_filters_for_remote_sessions); 1 external calls (vec!).

fn config_cwd_for_app_server_target(
    cwd: Option<&Path>,
    app_server_target: &AppServerTarget,
    environment_manager: &EnvironmentManager,
) -> std::io::Result<Option<AbsolutePathBuf>>

Purpose: Decides which current directory should be used while loading configuration. Remote workspaces and remote execution environments cannot safely use local path assumptions.

Data flow: It receives an optional CLI directory, the app server target, and the environment manager. For remote contexts it returns none; otherwise it canonicalizes the supplied path or current directory and returns an absolute path.

Call relations: run_main uses this before loading bootstrap config. Tests cover remote omission, local canonicalization, and missing directory errors.

Call graph: calls 4 internal fn (default_environment, uses_remote_workspace, current_dir, from_absolute_path); called by 6 (run_main, config_cwd_for_app_server_target_canonicalizes_embedded_cli_cwd, config_cwd_for_app_server_target_canonicalizes_local_daemon_cli_cwd, config_cwd_for_app_server_target_errors_for_missing_embedded_cli_cwd, config_cwd_for_app_server_target_omits_cwd_for_remote_exec_server, config_cwd_for_app_server_target_omits_cwd_for_remote_sessions); 1 external calls (canonicalize_existing_preserving_symlinks).

fn should_load_configured_environments(
    loader_overrides: &LoaderOverrides,
    app_server_target: &AppServerTarget,
) -> bool

Purpose: Decides whether startup should read user-configured execution environments. Remote workspaces skip this because their environment is not defined by local config.

Data flow: It reads loader override flags and the app server target. It returns true only when user config is allowed and the target is not a remote workspace.

Call relations: run_main calls this before creating the EnvironmentManager.

Call graph: calls 1 internal fn (uses_remote_workspace); called by 1 (run_main).

fn latest_session_cwd_filter(
    uses_remote_workspace: bool,
    remote_cwd_override: Option<&'a Path>,
    config: &'a Config,
    show_all: bool,
) -> Option<&'a Path>

Purpose: Chooses the directory filter for latest-session lookup. This keeps --last scoped to the current project unless the user asks to show all sessions.

Data flow: It receives remote/local status, an optional remote current-directory override, config, and a show-all flag. It returns no filter for show-all, the remote override for remote workspaces, or the config current directory for local sessions.

Call relations: run_ratatui_app uses this before latest resume/fork lookup, and tests verify the scope choices.

Call graph: called by 3 (run_ratatui_app, fork_last_filters_latest_session_by_cwd_unless_show_all, latest_session_cwd_filter_respects_scope_options).

fn app_server_target_for_launch(
    explicit_remote_endpoint: Option<RemoteAppServerEndpoint>,
    default_daemon_socket: Option<AbsolutePathBuf>,
    can_reuse_implicit_local_daemon: bool,
) -> AppS

Purpose: Chooses whether this run should use an explicit remote server, a reusable local daemon, or a fresh embedded server. This is a key routing decision during startup.

Data flow: It receives an explicit endpoint if any, a probed default daemon socket if any, and whether implicit daemon reuse is allowed. It prefers explicit remote, then reusable daemon, then embedded.

Call relations: run_main calls this after checking CLI/config constraints. Tests verify each branch.

Call graph: called by 4 (run_main, app_server_target_for_launch_prefers_explicit_remote_endpoint, app_server_target_for_launch_skips_local_daemon_when_launch_config_is_not_replayable, app_server_target_for_launch_uses_local_daemon_for_default_socket).

fn loader_overrides_are_default(loader_overrides: &LoaderOverrides) -> bool

Purpose: Checks whether config-loading options are still at their normal defaults. A reused daemon can only be trusted when it does not need special one-off config loading behavior.

Data flow: It receives loader overrides and returns true only if no custom config paths, ignored config sources, or special managed-config data are set.

Call relations: can_reuse_implicit_local_daemon uses this as one of the safety gates for daemon reuse.

Call graph: called by 1 (can_reuse_implicit_local_daemon).

fn can_reuse_implicit_local_daemon(
    cli_kv_overrides: &[(String, toml::Value)],
    loader_overrides: &LoaderOverrides,
    strict_config: bool,
    has_non_replayable_launch_overrides: bool,
) ->

Purpose: Decides whether startup may automatically reuse a local background daemon. It prevents reuse when the current launch includes settings the daemon cannot replay.

Data flow: It reads CLI config overrides, loader overrides, strict-config mode, and non-replayable launch flags. It returns true only when all are plain defaults.

Call relations: run_main uses this before probing the default daemon socket. Tests cover the conditions that disable reuse.

Call graph: calls 1 internal fn (loader_overrides_are_default); called by 1 (run_main).

async fn run_main(
    mut cli: Cli,
    arg0_paths: Arg0DispatchPaths,
    loader_overrides: LoaderOverrides,
    explicit_remote_endpoint: Option<RemoteAppServerEndpoint>,
) -> std::io::Result<AppEx

Purpose: Performs the full non-UI startup sequence for the TUI library. It parses launch choices, loads config, prepares logging/telemetry/database state, chooses the app server target, and then hands off to the terminal app runner.

Data flow: It receives parsed CLI data, paths for helper executables, config-loader overrides, and an optional explicit remote endpoint. It transforms these into final config, cloud config, app-server target, state/log database handles, feedback and telemetry layers, environment manager, and app launch overrides, then returns the app exit information.

Call relations: This is the main public runner used by the binary side of the TUI. After all setup succeeds, it calls run_ratatui_app; on unrecoverable config or auth errors it prints a message and exits.

Call graph: calls 21 internal fn (default, resolve_oss_provider, resolve_profile_v2_config_path, from_codex_home, from_env, from_optional_paths, new, originator, set_default_client_residency_requirement, add_dir_warning_message (+11 more)); 25 external calls (default, try_from_default_env, new, other, migrate_personality_if_needed, cloud_config_bundle_loader_for_storage, enforce_login_restrictions, record_process_start_once, sqlite_telemetry_recorder, install_process_db_telemetry (+15 more)).

async fn run_ratatui_app(
    cli: Cli,
    arg0_paths: Arg0DispatchPaths,
    loader_overrides: LoaderOverrides,
    strict_config: bool,
    app_server_target: AppServerTarget,
    remote_cwd_overri

Purpose: Runs the actual terminal UI after startup services are ready. It initializes the terminal, performs onboarding or session selection, starts or reuses the app server session, and launches App::run.

Data flow: It receives CLI data, config, app-server target, overrides, cloud config loader, feedback/logging/database services, and environment manager. It sets up panic handling and terminal restoration, may reload config after login/trust/resume choices, resolves resume or fork targets, bootstraps the app server, runs startup hook review, and returns the app’s exit information.

Call relations: run_main hands off here after process-level setup. This function then calls helpers for app server startup, login status, onboarding, session lookup, alternate-screen mode, and finally the main App::run loop.

Call graph: calls 29 internal fn (set_default_client_residency_requirement, thread_params_mode, uses_remote_workspace, new, new, write_config_batch, determine_alt_screen_mode, get_login_status, latest_session_cwd_filter, load_config_or_exit (+15 more)); called by 1 (run_main); 26 external calls (new, now, auth_keyring_backend_kind, clone, clone, run, cloud_config_bundle_loader_for_storage, find_codex_home, install, clone (+15 more)).

fn restore()

Purpose: Restores the terminal after the TUI is done or has failed. If restoration itself fails, it tells the user how to recover.

Data flow: It calls the TUI restore routine. On error, it writes a plain message to standard error suggesting reset or restarting the terminal.

Call relations: TerminalRestoreGuard::restore_silently uses this on normal guard cleanup and early error paths.

Call graph: calls 1 internal fn (restore_after_exit); called by 1 (restore_silently); 1 external calls (eprintln!).

fn new() -> Self

Purpose: Creates a guard that will restore the terminal unless told it has already done so. This protects users from being left in alternate-screen or raw terminal mode.

Data flow: It creates a TerminalRestoreGuard with its active flag set to true.

Call relations: run_ratatui_app creates this immediately after terminal initialization.

Call graph: called by 1 (run_ratatui_app).

fn restore(&mut self) -> color_eyre::Result<()>

Purpose: Restores the terminal and reports any restoration error to the caller. It is used when the caller can still return a structured error.

Data flow: It checks whether the guard is active. If so, it calls terminal restoration, marks itself inactive, and returns success or the restoration error.

Call relations: The update prompt path can call this before leaving the TUI to run an updater.

Call graph: calls 1 internal fn (restore_after_exit).

fn restore_silently(&mut self)

Purpose: Restores the terminal without returning an error. This is useful during cleanup paths where the app is already exiting.

Data flow: It checks the active flag, calls the best-effort restore helper, and then marks itself inactive.

Call relations: Early exits in run_ratatui_app call this, and the guard’s drop method calls it as a final safety net.

Call graph: calls 1 internal fn (restore); called by 1 (drop).

fn drop(&mut self)

Purpose: Automatically restores the terminal if the guard goes out of scope while still active. This is the backup plan for unexpected exits.

Data flow: When the guard is dropped, it calls silent restoration. The active flag prevents double restoration.

Call relations: Rust calls this automatically; it delegates to TerminalRestoreGuard::restore_silently.

Call graph: calls 1 internal fn (restore_silently).

fn determine_alt_screen_mode(no_alt_screen: bool, tui_alternate_screen: AltScreenMode) -> bool

Purpose: Decides whether the TUI should use the terminal’s alternate screen buffer. The alternate screen gives a full-screen app feel, while inline mode preserves scrollback.

Data flow: It receives the --no-alt-screen flag and the config value. The flag always disables alternate screen; otherwise every config mode except Never enables it.

Call relations: run_ratatui_app calls this just before configuring the TUI display mode. A test verifies the expected combinations.

Call graph: called by 1 (run_ratatui_app).

async fn get_login_status(
    app_server: &mut AppServerSession,
    config: &Config,
) -> color_eyre::Result<LoginStatus>

Purpose: Checks whether the user is logged in, without doing a heavier full app-server bootstrap. This avoids unnecessary model-list fetches and rate-limit work during startup.

Data flow: It receives the app server session and config. If the chosen provider does not require OpenAI-style auth, it returns not authenticated; otherwise it reads the account and maps API-key or ChatGPT accounts to login modes.

Call relations: run_ratatui_app calls this before deciding whether onboarding should show a login screen.

Call graph: calls 1 internal fn (read_account); called by 1 (run_ratatui_app); 1 external calls (AuthMode).

async fn load_config_or_exit(
    cli_kv_overrides: Vec<(String, toml::Value)>,
    overrides: ConfigOverrides,
    loader_overrides: LoaderOverrides,
    cloud_config_bundle: CloudConfigBundleLoader,

Purpose: Loads the full runtime configuration and exits the process with a message if it fails. It is the simple version used when no fallback current directory is needed.

Data flow: It receives CLI overrides, structured overrides, loader overrides, cloud config loader, and strict mode. It forwards them to the fallback-capable loader with no fallback directory and returns a config on success.

Call relations: run_main and run_ratatui_app use this after initial setup, onboarding, and some picker flows.

Call graph: calls 1 internal fn (load_config_or_exit_with_fallback_cwd); called by 2 (run_main, run_ratatui_app).

async fn load_config_or_exit_with_fallback_cwd(
    cli_kv_overrides: Vec<(String, toml::Value)>,
    overrides: ConfigOverrides,
    loader_overrides: LoaderOverrides,
    cloud_config_bundle: CloudC

Purpose: Loads the full runtime configuration, optionally using a fallback current directory for resumed or forked sessions. On failure it prints the error and exits.

Data flow: It builds a ConfigBuilder from CLI overrides, harness overrides, loader overrides, strict mode, cloud config, and fallback directory. Success returns the config; failure writes to standard error and terminates the process.

Call relations: load_config_or_exit delegates here, and run_ratatui_app calls it directly when resume/fork changes the effective directory.

Call graph: called by 2 (load_config_or_exit, run_ratatui_app); 3 external calls (default, eprintln!, exit).

async fn load_bootstrap_config_or_exit(
    codex_home: &Path,
    cwd: Option<&AbsolutePathBuf>,
    cli_kv_overrides: Vec<(String, codex_config::TomlValue)>,
    loader_overrides: LoaderOverrides,

Purpose: Loads just enough config-file data to make early startup decisions such as cloud config and OSS provider selection. It gives detailed source-formatted errors for config file problems.

Data flow: It receives Codex home, optional config current directory, CLI overrides, loader options, strict mode, and cloud config loader. It loads the TOML layer stack and returns it; on error it formats the problem and exits.

Call relations: run_main calls this before full config construction, including an additional load when OSS provider resolution needs cloud-managed settings.

Call graph: calls 1 internal fn (load_config_toml_with_layer_stack); called by 1 (run_main); 2 external calls (eprintln!, exit).

fn should_show_trust_screen(config: &Config) -> bool

Purpose: Decides whether the user still needs to choose whether the current project directory is trusted. Trust affects what actions Codex may take automatically.

Data flow: It reads the active project trust level from config and returns true only when no trust decision exists.

Call relations: run_ratatui_app uses this for onboarding and startup prompts. Tests cover trusted, untrusted, and Windows-related cases.

Call graph: called by 4 (run_ratatui_app, untrusted_project_skips_trust_prompt, windows_shows_trust_prompt_with_sandbox, windows_shows_trust_prompt_without_sandbox).

fn should_show_onboarding(
    login_status: LoginStatus,
    config: &Config,
    show_trust_screen: bool,
) -> bool

Purpose: Decides whether any onboarding screen should be shown at startup. Onboarding appears if trust is undecided or login is required.

Data flow: It receives login status, config, and whether the trust screen is needed. A needed trust screen immediately returns true; otherwise it asks whether the login screen is needed.

Call relations: run_ratatui_app uses this before running onboarding, and it delegates login-specific logic to should_show_login_screen.

Call graph: calls 1 internal fn (should_show_login_screen); called by 1 (run_ratatui_app).

fn should_show_login_screen(login_status: LoginStatus, config: &Config) -> bool

Purpose: Decides whether startup should prompt the user to log in. Providers that do not require OpenAI-style authentication skip this entirely.

Data flow: It receives login status and config. It returns false for providers without required auth, and otherwise returns true only when the user is not authenticated.

Call relations: run_ratatui_app uses it to configure onboarding, and should_show_onboarding uses it as the login part of the onboarding decision.

Call graph: called by 2 (run_ratatui_app, should_show_onboarding).

async fn build_config(temp_dir: &TempDir) -> std::io::Result<Config>

Purpose: Creates a basic test configuration rooted in a temporary directory. It keeps tests isolated from the user’s real Codex home.

Data flow: It receives a temporary directory, passes its path into the config builder, and returns the built config.

Call relations: Many tests call this helper before exercising startup, session lookup, trust, or config behavior.

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

fn write_session_rollout(
        codex_home: &Path,
        filename_ts: &str,
        meta_rfc3339: &str,
        preview: &str,
        model_provider: &str,
        cwd: &Path,
    ) -> color_eyre

Purpose: Writes a small fake saved-session rollout file for tests. This lets session lookup tests behave as if a real past conversation exists.

Data flow: It receives Codex home, timestamps, preview text, model provider, and current directory. It creates the expected session file path, writes JSON lines with metadata and a user message, sets the file timestamp, and returns the new thread ID.

Call relations: Session lookup tests use this to create old and new sessions that the embedded app server can discover.

Call graph: calls 1 internal fn (from_string); 12 external calls (default, join, to_path_buf, new_v4, parse_from_rfc3339, format!, json!, to_value, new, new (+2 more)).

fn startup_removes_legacy_tui_log_file() -> std::io::Result<()>

Purpose: Verifies that startup cleanup deletes the old shared TUI log file.

Data flow: It creates a temporary log file, calls the cleanup helper, and checks that the file no longer exists.

Call relations: This directly tests remove_legacy_tui_log_file.

Call graph: calls 1 internal fn (remove_legacy_tui_log_file); 4 external calls (new, assert!, create_dir_all, write).

async fn start_test_embedded_app_server(
        config: Config,
    ) -> color_eyre::Result<InProcessAppServerClient>

Purpose: Starts a real embedded app server for tests using safe defaults. It avoids duplicating setup code across app-server-related tests.

Data flow: It receives config, initializes state database, builds default test services, and returns an in-process app server client.

Call relations: Tests that need app-server RPCs or session lookup call this helper, which calls the production embedded startup path.

Call graph: calls 5 internal fn (default, default_for_tests, new, init_state_db_for_app_server_target, start_embedded_app_server); 4 external calls (new, new, default, default).

fn alternate_screen_auto_uses_alt_screen()

Purpose: Checks the rules for alternate-screen mode. It ensures config and the --no-alt-screen flag combine as intended.

Data flow: It calls the mode-deciding helper with several inputs and asserts the expected booleans.

Call relations: This protects determine_alt_screen_mode, which run_ratatui_app uses before launching the UI.

Call graph: 1 external calls (assert!).

fn session_target_display_label_falls_back_to_thread_id()

Purpose: Confirms that a session target without a file path still has a useful display label. The fallback label uses the thread ID.

Data flow: It creates a target with no path and checks that its display label is thread <id>.

Call relations: This indirectly protects resume picker display behavior.

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

fn resolve_remote_addr_accepts_websocket_url()

Purpose: Verifies that a plain WebSocket address with an explicit port is accepted.

Data flow: It resolves ws://127.0.0.1:4500 and checks that the normalized endpoint is a WebSocket URL with no auth token.

Call relations: This covers the WebSocket branch of resolve_remote_addr.

Call graph: 1 external calls (assert_eq!).

fn resolve_remote_addr_accepts_secure_websocket_url()

Purpose: Verifies that a secure WebSocket address with an explicit default port is accepted.

Data flow: It resolves a wss:// URL and checks that URL normalization still produces the expected endpoint.

Call relations: This protects the explicit-port detection used by resolve_remote_addr.

Call graph: 1 external calls (assert_eq!).

fn resolve_remote_addr_accepts_default_socket() -> color_eyre::Result<()>

Purpose: Checks that unix:// means the default Codex app-server socket.

Data flow: It finds Codex home, resolves unix://, and compares the result with the standard control socket path.

Call relations: This tests the default Unix socket path branch of resolve_remote_addr.

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

fn resolve_remote_addr_accepts_relative_socket_path() -> color_eyre::Result<()>

Purpose: Checks that relative Unix socket paths are accepted and made absolute relative to the current directory.

Data flow: It resolves unix://codex.sock and compares the endpoint with the expected absolute path wrapper.

Call relations: This covers the relative-path branch of resolve_remote_addr.

Call graph: 1 external calls (assert_eq!).

fn resolve_remote_addr_accepts_absolute_socket_path() -> color_eyre::Result<()>

Purpose: Checks that absolute Unix socket paths are accepted as remote endpoints.

Data flow: It creates a temporary absolute path, formats it as unix://..., resolves it, and compares the endpoint.

Call relations: This covers the absolute-path branch of resolve_remote_addr.

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

fn resolve_remote_addr_rejects_invalid_remote_addresses()

Purpose: Verifies that incomplete or unsupported remote address strings fail clearly.

Data flow: It tries several invalid addresses and checks that each error mentions the expected accepted formats.

Call relations: This directly protects resolve_remote_addr validation.

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

async fn default_daemon_auto_connect_skips_missing_socket() -> color_eyre::Result<()>

Purpose: Checks that daemon auto-connect does nothing when the default socket is absent.

Data flow: It creates a temporary Codex home with no socket, probes it, and asserts that no socket path is returned.

Call relations: This tests the missing-socket path in maybe_probe_default_daemon_socket.

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

async fn default_daemon_auto_connect_probes_socket_only() -> color_eyre::Result<()>

Purpose: On Unix, verifies that auto-connect recognizes a live default daemon socket.

Data flow: It creates the socket directory, binds a Unix listener at the standard path, probes, and expects that path back.

Call relations: This tests the successful socket-probe path used by run_main.

Call graph: calls 1 internal fn (bind); 4 external calls (new, assert_eq!, app_server_control_socket_path, create_dir_all).

fn app_server_target_for_launch_uses_local_daemon_for_default_socket() -> color_eyre::Result<()>

Purpose: Checks that startup chooses a local daemon when reuse is allowed and a default socket was found.

Data flow: It passes no explicit remote endpoint, a socket path, and reuse allowed; then it asserts the target is LocalDaemon.

Call relations: This directly tests app_server_target_for_launch and its local-daemon branch.

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

fn app_server_target_for_launch_prefers_explicit_remote_endpoint() -> color_eyre::Result<()>

Purpose: Checks that an explicitly supplied remote endpoint wins over an auto-detected local daemon.

Data flow: It passes both an explicit endpoint and a default socket, then asserts that the result is Remote.

Call relations: This protects the priority order inside app_server_target_for_launch.

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

fn app_server_target_for_launch_skips_local_daemon_when_launch_config_is_not_replayable() -> color_eyre::Result<()>

Purpose: Checks that startup does not reuse a daemon when the current launch has special settings the daemon cannot reproduce.

Data flow: It passes a default socket but marks reuse as disallowed, then expects the embedded target.

Call relations: This verifies the safety gate used before daemon reuse.

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

fn can_reuse_implicit_local_daemon_requires_default_launch_config() -> color_eyre::Result<()>

Purpose: Verifies the conditions required for implicit local daemon reuse. Any non-default launch setting should disable reuse.

Data flow: It tries default inputs and then variations with CLI overrides, ignored user config, strict config, and non-replayable flags, checking true only for the default case.

Call relations: This directly tests can_reuse_implicit_local_daemon and its default-loader helper.

Call graph: 3 external calls (assert!, default, vec!).

fn should_load_configured_environments_for_local_daemon() -> color_eyre::Result<()>

Purpose: Confirms that local daemon mode still loads configured local environments when user config is allowed.

Data flow: It builds a local daemon target and checks that environment loading is enabled.

Call relations: This tests should_load_configured_environments, which run_main uses before creating an environment manager.

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

async fn latest_session_lookup_params_keep_local_filters_for_embedded_sessions() -> std::io::Result<()>

Purpose: Checks that latest-session lookup for embedded sessions keeps local model-provider and directory filters.

Data flow: It builds config and a project path, creates lookup parameters, and asserts provider, directory, and database-only fields.

Call relations: This protects latest_session_lookup_params for embedded startup.

Call graph: calls 1 internal fn (latest_session_lookup_params); 4 external calls (new, assert!, assert_eq!, build_config).

async fn latest_session_lookup_params_keep_local_filters_for_local_daemon_sessions() -> color_eyre::Result<()>

Purpose: Checks that local daemon session lookup behaves like embedded lookup for local filters.

Data flow: It builds a local daemon target and asserts that lookup parameters include the local model provider and current directory filter.

Call relations: This verifies local daemon behavior in latest_session_lookup_params.

Call graph: calls 2 internal fn (latest_session_lookup_params, relative_to_current_dir); 3 external calls (new, assert_eq!, build_config).

async fn latest_session_lookup_params_omit_local_filters_for_remote_sessions() -> std::io::Result<()>

Purpose: Checks that remote session lookup does not include local-only filters.

Data flow: It builds lookup parameters with remote mode enabled and asserts that model provider and current-directory filters are omitted.

Call relations: This protects the remote branch of latest_session_lookup_params.

Call graph: calls 1 internal fn (latest_session_lookup_params); 3 external calls (new, assert_eq!, build_config).

async fn latest_session_lookup_params_can_include_non_interactive_sources() -> std::io::Result<()>

Purpose: Verifies that latest-session lookup can include non-interactive sessions when requested.

Data flow: It builds parameters with the include flag enabled and checks that CLI, VS Code, Exec, and AppServer sources are listed.

Call relations: This tests resume_source_kinds through latest_session_lookup_params.

Call graph: calls 1 internal fn (latest_session_lookup_params); 3 external calls (new, assert_eq!, build_config).

async fn latest_session_lookup_params_keep_explicit_cwd_filter_for_remote_sessions() -> std::io::Result<()>

Purpose: Checks that a remote workspace can still use an explicit remote current-directory filter.

Data flow: It passes a remote path string as the filter and confirms it appears in the lookup parameters while local provider filtering stays absent.

Call relations: This covers remote filtered lookup in latest_session_lookup_params.

Call graph: calls 1 internal fn (latest_session_lookup_params); 4 external calls (new, new, assert_eq!, build_config).

async fn latest_session_cwd_filter_respects_scope_options() -> std::io::Result<()>

Purpose: Verifies how latest-session directory scoping is chosen. Local sessions use the config directory, show-all removes the filter, and remote sessions use the remote override.

Data flow: It calls the filter helper for local, show-all, and remote cases, then compares each result.

Call relations: This directly tests latest_session_cwd_filter, which run_ratatui_app uses for --last operations.

Call graph: calls 1 internal fn (latest_session_cwd_filter); 4 external calls (new, new, assert_eq!, build_config).

async fn fork_last_filters_latest_session_by_cwd_unless_show_all() -> color_eyre::Result<()>

Purpose: Checks that fork --last chooses the latest session in the current project unless the user asks to show all sessions.

Data flow: It creates two fake sessions in different directories, starts an embedded server, performs scoped and global latest lookups, and compares the returned thread IDs.

Call relations: This exercises latest_session_cwd_filter and lookup_latest_session_target_with_app_server together.

Call graph: calls 3 internal fn (new, latest_session_cwd_filter, lookup_latest_session_target_with_app_server); 8 external calls (default, new, InProcess, assert_eq!, default, create_dir_all, start_test_embedded_app_server, write_session_rollout).

async fn latest_session_lookup_falls_back_for_rollout_missing_from_state_db() -> color_eyre::Result<()>

Purpose: Verifies that latest-session lookup can still find a rollout file that was not in the state database. This protects compatibility with legacy writers.

Data flow: It starts an embedded server, writes a fake rollout after backfill, asks for the latest session, and checks that the fallback scan finds it.

Call relations: This tests the scan-and-repair fallback inside lookup_latest_session_target_with_app_server.

Call graph: calls 2 internal fn (new, lookup_latest_session_target_with_app_server); 8 external calls (default, new, InProcess, assert_eq!, default, create_dir_all, start_test_embedded_app_server, write_session_rollout).

async fn config_cwd_for_app_server_target_omits_cwd_for_remote_sessions() -> std::io::Result<()>

Purpose: Checks that config loading does not try to canonicalize a remote-only path on the local machine.

Data flow: It supplies a deliberately non-local-looking path with a remote target and expects no config current directory.

Call relations: This protects the remote branch of config_cwd_for_app_server_target.

Call graph: calls 3 internal fn (default_for_tests, config_cwd_for_app_server_target, relative_to_current_dir); 3 external calls (new, assert_eq!, cfg!).

async fn config_cwd_for_app_server_target_canonicalizes_embedded_cli_cwd() -> std::io::Result<()>

Purpose: Checks that embedded startup canonicalizes a supplied local current directory.

Data flow: It passes a temporary directory as CLI cwd and expects the canonical absolute path back.

Call relations: This tests local path handling in config_cwd_for_app_server_target.

Call graph: calls 2 internal fn (default_for_tests, config_cwd_for_app_server_target); 2 external calls (new, assert_eq!).

async fn config_cwd_for_app_server_target_canonicalizes_local_daemon_cli_cwd() -> std::io::Result<()>

Purpose: Checks that local daemon startup also canonicalizes a supplied local current directory.

Data flow: It passes a temporary directory with a local daemon target and expects the canonical absolute path.

Call relations: This confirms local daemon mode follows local cwd rules.

Call graph: calls 3 internal fn (default_for_tests, config_cwd_for_app_server_target, relative_to_current_dir); 2 external calls (new, assert_eq!).

async fn config_cwd_for_app_server_target_errors_for_missing_embedded_cli_cwd() -> std::io::Result<()>

Purpose: Checks that embedded startup reports an error when the requested local current directory does not exist.

Data flow: It passes a missing path and asserts that the result is a not-found error.

Call relations: This protects the error path in config_cwd_for_app_server_target.

Call graph: calls 2 internal fn (default_for_tests, config_cwd_for_app_server_target); 2 external calls (new, assert_eq!).

async fn config_cwd_for_app_server_target_omits_cwd_for_remote_exec_server() -> std::io::Result<()>

Purpose: Checks that a remote execution environment also suppresses local current-directory canonicalization, even with an embedded app server target.

Data flow: It creates a test environment manager marked remote, passes a non-local-looking path, and expects no config cwd.

Call relations: This tests the environment-manager branch of config_cwd_for_app_server_target.

Call graph: calls 3 internal fn (create_for_tests, new, config_cwd_for_app_server_target); 4 external calls (new, assert_eq!, cfg!, current_exe).

async fn windows_shows_trust_prompt_without_sandbox() -> std::io::Result<()>

Purpose: Verifies that an undecided project trust level causes the trust prompt to appear, even when Windows sandboxing is disabled.

Data flow: It builds config, clears the trust level, disables sandboxing, and checks that the trust screen is needed.

Call relations: This tests should_show_trust_screen.

Call graph: calls 1 internal fn (should_show_trust_screen); 3 external calls (new, assert!, build_config).

async fn embedded_app_server_supports_thread_start_rpc() -> color_eyre::Result<()>

Purpose: Checks that the embedded app server can accept a basic thread-start request.

Data flow: It starts a test embedded server, sends a thread/start request for an ephemeral thread, checks that an ID is returned, and shuts the server down.

Call relations: This verifies the embedded startup path used by start_embedded_app_server.

Call graph: 6 external calls (new, Integer, default, assert!, build_config, start_test_embedded_app_server).

async fn lookup_session_target_by_name_uses_backend_title_search() -> color_eyre::Result<()>

Purpose: Verifies that session lookup by name uses the backend title search and returns the right path and thread ID.

Data flow: It creates state database metadata for a titled session, starts an embedded app server, searches by title, and compares the returned target.

Call relations: This directly tests lookup_session_target_by_name_with_app_server.

Call graph: calls 5 internal fn (new, new, init, new, lookup_session_target_by_name_with_app_server); 12 external calls (pin, new, InProcess, assert_eq!, parse_from_rfc3339, format!, from_value, json!, create_dir_all, write (+2 more)).

async fn embedded_app_server_start_failure_is_returned() -> color_eyre::Result<()>

Purpose: Checks that embedded app-server startup failures are returned with useful context.

Data flow: It calls the generic embedded startup helper with a fake starter that returns an error, then asserts the error text includes embedded startup context.

Call relations: This tests the error wrapping in start_embedded_app_server_with.

Call graph: calls 4 internal fn (default, default_for_tests, new, start_embedded_app_server_with); 8 external calls (new, new, new, default, assert!, default, panic!, build_config).

async fn embedded_state_db_failure_is_typed_for_cli_recovery() -> color_eyre::Result<()>

Purpose: Verifies that embedded state database initialization failures keep typed context for recovery code.

Data flow: It makes the SQLite home path invalid by occupying it with a file, initializes state DB, extracts the typed startup error, and checks path and detail text.

Call relations: This protects init_state_db_for_app_server_target error conversion.

Call graph: calls 1 internal fn (init_state_db_for_app_server_target); 6 external calls (new, assert!, assert_eq!, panic!, write, build_config).

async fn embedded_state_db_corruption_preserves_failed_database_for_cli_recovery() -> color_eyre::Result<()>

Purpose: Checks that state database corruption errors identify the actual corrupted database file.

Data flow: It writes invalid data into the logs database path, attempts embedded state initialization, extracts the typed error, and checks that corruption details are preserved.

Call relations: This tests the corruption-reporting branch of init_state_db_for_app_server_target.

Call graph: calls 1 internal fn (init_state_db_for_app_server_target); 8 external calls (new, assert!, assert_eq!, logs_db_path, panic!, create_dir_all, write, build_config).

async fn windows_shows_trust_prompt_with_sandbox() -> std::io::Result<()>

Purpose: Verifies that an undecided project trust level still triggers the trust prompt when Windows sandboxing is enabled.

Data flow: It builds config, clears trust level, enables sandboxing, and asserts that the trust prompt is shown.

Call relations: This tests should_show_trust_screen across platform-sensitive setup.

Call graph: calls 1 internal fn (should_show_trust_screen); 4 external calls (new, assert!, cfg!, build_config).

async fn untrusted_project_skips_trust_prompt() -> std::io::Result<()>

Purpose: Confirms that a project explicitly marked untrusted does not ask for another trust decision.

Data flow: It sets the project trust level to untrusted and checks that the trust screen is not needed.

Call relations: This protects the simple none means undecided rule in should_show_trust_screen.

Call graph: calls 1 internal fn (should_show_trust_screen); 3 external calls (new, assert!, build_config).

async fn config_rebuild_changes_trust_defaults_with_cwd() -> std::io::Result<()>

Purpose: Verifies that rebuilding config with a different current directory changes project-specific trust defaults. This matters when resume or fork moves the effective directory.

Data flow: It writes config entries for trusted and untrusted directories, builds config for each directory, and checks the resulting approval policy.

Call relations: This supports the config-reload behavior in run_ratatui_app after session selection.

Call graph: calls 1 internal fn (without_managed_config_for_tests); 7 external calls (default, new, assert_eq!, default, format!, create_dir_all, write).

async fn theme_warning_uses_final_config() -> std::io::Result<()>

Purpose: Checks that syntax highlighting theme validation uses the final config, not an earlier config loaded before onboarding or resume/fork.

Data flow: It builds an initial config, then simulates a final config with an invalid theme, validates that theme, and checks that the warning lands in final startup warnings.

Call relations: This protects the ordering in run_ratatui_app, where theme setup happens after the last possible config reload.

Call graph: 4 external calls (new, assert!, assert_eq!, build_config).

fn new(lmstudio_status: ProviderStatus, ollama_status: ProviderStatus) -> io::Result<Self>

Purpose: Builds the on-screen provider selection widget. It prepares the text, provider status lines, selectable options, and initial state before anything is drawn.

Data flow: It receives the current LM Studio and Ollama status values. It turns those into display rows with colored symbols, builds a prompt explaining what the user should do, starts with the first provider option selected, and returns a ready-to-render widget.

Call relations: This is used by the startup provider chooser before showing the terminal prompt. The test also uses it to create a widget and check that keyboard navigation works. While building the prompt, it asks get_status_symbol_and_color how each status should look.

Call graph: calls 1 internal fn (get_status_symbol_and_color); called by 2 (select_oss_provider, ctrl_h_l_move_provider_selection); 3 external calls (from, new, vec!).

fn get_confirmation_prompt_height(&self, width: u16) -> u16

Purpose: Calculates how many terminal rows the explanatory prompt needs at a given width. This keeps the layout from overlapping when the terminal is narrow or wide.

Data flow: It receives a width in terminal columns, asks the prompt how many wrapped lines it will occupy, and returns that count as a height.

Call relations: The drawing code uses this before splitting the screen into prompt and button areas. desired_height also uses it when another part of the interface wants to know how much vertical space the widget needs.

Call graph: called by 2 (desired_height, render_ref); 1 external calls (line_count).

fn handle_key_event(&mut self, key: KeyEvent) -> Option<String>

Purpose: Receives a keyboard event and updates the widget if the key was actually pressed. If the key completes the choice, it returns the selected provider string.

Data flow: It takes one key event. If the event is a real key press, it passes it to the selection-key logic. Afterward, if the widget has been marked done, it returns the stored selection; otherwise it returns nothing.

Call relations: This is the widget’s main input doorway during the selection screen. It delegates the details of what each key means to handle_select_key, then reports completion back to the surrounding startup loop.

Call graph: calls 1 internal fn (handle_select_key).

fn normalize_keycode(code: KeyCode) -> KeyCode

Purpose: Makes letter keys easier to compare by treating uppercase and lowercase as the same. This lets shortcuts like L and l mean the same thing.

Data flow: It receives a key code. If it is a character, it converts that character to lowercase; if it is any other kind of key, such as Enter or Escape, it leaves it unchanged and returns it.

Call relations: The provider shortcut logic uses this while matching a typed key against each option’s configured shortcut. handle_select_key relies on it so shortcut matching is case-insensitive.

Call graph: 1 external calls (Char).

fn handle_select_key(&mut self, key_event: KeyEvent)

Purpose: Interprets the user’s key press while the provider picker is open. It moves the highlighted option, chooses a provider, or cancels depending on the key.

Data flow: It receives a key event and compares it against known actions. Ctrl+C stores a cancellation marker, left and right movement keys change the selected index, Enter stores the currently highlighted provider, Escape stores the LM Studio provider, and letter shortcuts store the matching provider.

Call relations: handle_key_event calls this whenever a real key press arrives. When a key means the user has made a final choice, this function hands the chosen string to send_decision; when it needs shortcut matching, it uses normalize_keycode.

Call graph: calls 1 internal fn (send_decision); called by 1 (handle_key_event); 1 external calls (normalize_keycode).

fn send_decision(&mut self, selection: String)

Purpose: Records that the user has made a final choice. After this runs, the widget is considered complete and can be removed.

Data flow: It receives the selected provider string, saves it inside the widget, and flips the done flag to true. It does not return anything; it changes the widget’s stored state.

Call relations: The key-handling logic calls this whenever a key press resolves the prompt, such as Enter, Escape, Ctrl+C, or a provider shortcut. Later, handle_key_event can return the stored selection because this function has marked the widget finished.

Call graph: called by 1 (handle_select_key).

fn is_complete(&self) -> bool

Purpose: Reports whether the widget has already received a final choice. Other code can use this to know whether it should stop showing the prompt.

Data flow: It reads the widget’s internal done flag and returns true or false. It does not change anything.

Call relations: This is a small status check for callers that need to know whether the selection screen is finished. It reflects the state set by send_decision.

fn desired_height(&self, width: u16) -> u16

Purpose: Tells the surrounding interface how tall the widget wants to be. This helps reserve enough room for both the explanatory prompt and the provider buttons.

Data flow: It receives the available width, calculates the wrapped prompt height, adds one row per selectable option, and returns the total desired height.

Call relations: It builds on get_confirmation_prompt_height instead of recalculating that directly. This is useful when a parent view needs to lay out the widget before rendering it.

Call graph: calls 1 internal fn (get_confirmation_prompt_height).

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Purpose: Draws the provider picker into the terminal screen buffer. It lays out the prompt, selectable provider buttons, and the description of the currently highlighted option.

Data flow: It receives a rectangular screen area and a mutable drawing buffer. It splits the area into sections, styles the selected option differently from the others, renders the status prompt, draws the provider buttons, and writes the selected provider’s description below.

Call relations: The startup selection loop calls this each time it redraws the terminal. It asks get_confirmation_prompt_height how much space the prompt needs, then uses Ratatui layout and rendering tools to paint the widget.

Call graph: calls 1 internal fn (get_confirmation_prompt_height); 9 external calls (Length, Min, default, horizontal, vertical, from, new, clone, new).

fn get_status_symbol_and_color(status: &ProviderStatus) -> (&'static str, Color)

Purpose: Chooses the visible symbol and color for a provider’s running status. This turns an internal status value into something a human can read quickly.

Data flow: It receives a provider status. Running becomes a green filled dot, not running becomes a red empty dot, and unknown becomes a yellow question mark; it returns both the symbol and the color.

Call relations: OssSelectionWidget::new calls this while building the status list shown in the prompt. It keeps the display rules in one place so the widget setup stays readable.

Call graph: called by 1 (new).

async fn select_oss_provider() -> io::Result<OssProviderSelection>

Purpose: Runs the full provider selection process from start to finish. It checks local provider availability, auto-selects when possible, or opens the terminal UI when the user must decide.

Data flow: It first checks LM Studio and Ollama. If only one is running, it returns that provider with a flag saying it was not manually selected. Otherwise it creates the selection widget, switches the terminal into a special interactive mode, repeatedly draws the prompt and reads keys, then returns the chosen provider with a flag saying the user selected it.

Call relations: This is called during the main startup path. It relies on check_lmstudio_status and check_ollama_status for the initial probe, creates the widget with OssSelectionWidget::new, uses terminal drawing and keyboard reading while the prompt is visible, and restores the terminal before returning.

Call graph: calls 3 internal fn (new, check_lmstudio_status, check_ollama_status); called by 1 (run_main); 7 external calls (new, disable_raw_mode, enable_raw_mode, read, execute!, stdout, new).

async fn check_lmstudio_status() -> ProviderStatus

Purpose: Checks whether LM Studio appears to be running on its default local port. It translates a low-level network check into the simple status used by the UI.

Data flow: It calls the shared port checker with LM Studio’s default port. A successful HTTP response becomes Running, a failed connection becomes NotRunning, and an unexpected checking error becomes Unknown.

Call relations: select_oss_provider calls this before deciding whether to auto-pick or show the prompt. It delegates the actual HTTP request work to check_port_status.

Call graph: calls 1 internal fn (check_port_status); called by 1 (select_oss_provider).

async fn check_ollama_status() -> ProviderStatus

Purpose: Checks whether Ollama appears to be running on its default local port. It produces the same simple status categories used for display and auto-selection.

Data flow: It calls the shared port checker with Ollama’s default port. A successful HTTP response becomes Running, a failed connection becomes NotRunning, and an unexpected checking error becomes Unknown.

Call relations: select_oss_provider calls this alongside the LM Studio check. It uses check_port_status so both provider checks follow the same network-checking behavior.

Call graph: calls 1 internal fn (check_port_status); called by 1 (select_oss_provider).

async fn check_port_status(port: u16) -> io::Result<bool>

Purpose: Tests whether something useful is responding at a local HTTP port. This is the basic probe used to guess whether a local provider server is running.

Data flow: It receives a port number, builds an HTTP client with a short two-second timeout, sends a GET request to localhost on that port, and returns true if the response status is successful. If the connection fails, it returns false; if the client cannot be built, it returns an input/output error.

Call relations: Both provider-specific status checks call this with their own default ports. By keeping the probing logic here, LM Studio and Ollama status checks differ only in which port they ask about.

Call graph: called by 2 (check_lmstudio_status, check_ollama_status); 3 external calls (from_secs, builder, format!).

fn ctrl_h_l_move_provider_selection()

Purpose: Verifies that Ctrl+L moves the provider selection to the right and Ctrl+H moves it back to the left. This protects keyboard navigation that is important before the main app keymap is available.

Data flow: It creates a widget with unknown provider statuses, checks that the first option starts selected, sends a Ctrl+L key event and checks that the second option is selected, then sends a Ctrl+H key event and checks that selection returns to the first option.

Call relations: The test builds the widget through OssSelectionWidget::new and exercises its key-event path. It exists because this startup wizard has its own built-in movement keys rather than relying on the main application key configuration.

Call graph: calls 1 internal fn (new); 3 external calls (Char, new, assert_eq!).

async fn load_startup_hooks_review_entry(
    request_handle: AppServerRequestHandle,
    cwd: PathBuf,
) -> HooksListEntry

Purpose: Loads the hook information for the current folder before the startup review is shown. If the app server cannot provide the hook list, it logs a warning and returns an empty hook entry so startup can keep going safely.

Data flow: It receives an app server request handle and a current working directory path. It asks the server for the hook list, picks the entry that belongs to that directory, and returns it. If the request fails, it returns the same directory with no hooks, warnings, or errors.

Call relations: This is the loading step that prepares data for the later review decision. It calls the hook-list fetching code and the helper that finds the matching directory entry, then leaves the caller with a single HooksListEntry to inspect.

Call graph: calls 2 internal fn (fetch_hooks_list, hooks_list_entry_for_cwd); 3 external calls (clone, new, warn!).

async fn maybe_run_startup_hooks_review(
    app_server: &mut AppServerSession,
    tui: &mut Tui,
    config: &Config,
    bypass_hook_trust: bool,
    entry: HooksListEntry,
) -> Result<StartupHooks

Purpose: Decides whether the startup hook review screen should appear. It is the gate between normal startup and the safety prompt.

Data flow: It receives the app server session, terminal UI, configuration, a bypass flag, and the hook entry. It checks whether review is needed; if not, it returns Continue. If review is needed, it starts the interactive review screen and returns the user’s chosen outcome.

Call relations: The main terminal app startup calls this from run_ratatui_app. It first asks review_is_needed for the decision, and only hands control to run_startup_hooks_review_app when the user must be prompted.

Call graph: calls 2 internal fn (review_is_needed, run_startup_hooks_review_app); called by 1 (run_ratatui_app).

async fn run_startup_hooks_review_app(
    app_server: &mut AppServerSession,
    tui: &mut Tui,
    config: &Config,
    entry: HooksListEntry,
) -> Result<StartupHooksReviewOutcome>

Purpose: Runs the interactive startup prompt where the user chooses what to do about changed or untrusted hooks. It owns the short event loop for this prompt.

Data flow: It receives the live app server session, terminal UI, user configuration, and hook entry. It builds a keymap, creates the selection view, draws it, then reads terminal events. Depending on the chosen item, it returns either Continue or OpenHooksBrowser; for “trust all,” it writes trust records to the server and either continues or redraws with an error.

Call relations: maybe_run_startup_hooks_review calls this when a review is required. Inside the loop it uses selection_view to build the screen, draw_view to paint it, selected_choice to interpret completed selections, and write_hook_trusts to save trust decisions through the app server.

Call graph: calls 7 internal fn (new, request_handle, write_hook_trusts, from_config, draw_view, selected_choice, selection_view); called by 1 (maybe_run_startup_hooks_review); 4 external calls (event_stream, matches!, pin!, OpenHooksBrowser).

fn selected_choice(view: &mut ListSelectionView) -> Option<StartupHooksReviewSelection>

Purpose: Turns the selection widget’s completed row into the meaning the startup flow needs. It translates list positions into actions like review, trust all, or continue without trusting.

Data flow: It receives a mutable selection view. If the view has not finished a selection, it returns nothing. If a selection is complete, it takes the selected index and converts it into a StartupHooksReviewSelection value.

Call relations: run_startup_hooks_review_app calls this after keyboard input. The review loop depends on it to know whether to redraw and wait, open the hooks browser, save trust, or continue.

Call graph: calls 2 internal fn (is_complete, take_last_selected_index); called by 1 (run_startup_hooks_review_app).

fn selection_view(
    entry: &HooksListEntry,
    trust_all_error: Option<&str>,
    trusting_all: bool,
    app_event_tx: AppEventSender,
    keymap: &RuntimeKeymap,
) -> ListSelectionView

Purpose: Builds the reusable list widget that appears in the startup prompt. It combines the visible prompt content with the event sender and keyboard bindings.

Data flow: It receives the hook entry, an optional trust error message, a flag saying whether trust-all is currently in progress, an app event sender, and the runtime keymap. It creates selection parameters and returns a ListSelectionView ready to draw and receive key events.

Call relations: run_startup_hooks_review_app uses this whenever the prompt state changes, including the initial prompt, the disabled “Trusting hooks...” state, and the error state. The rendering tests also call it to verify what users will see.

Call graph: calls 2 internal fn (new, selection_view_params); called by 3 (run_startup_hooks_review_app, renders_prompt, renders_prompt_with_trust_error).

fn selection_view_params(
    entry: &HooksListEntry,
    trust_all_error: Option<&str>,
    trusting_all: bool,
    keymap: &RuntimeKeymap,
) -> SelectionViewParams

Purpose: Creates the text and menu items for the startup review prompt. This is where the user-facing wording is assembled.

Data flow: It receives the hook entry, an optional error, a flag for the trust-in-progress state, and the keymap. It counts hooks needing review, builds a header with warning text, optionally adds either an error message or “Trusting hooks...”, and returns menu parameters with three choices and a keyboard hint footer.

Call relations: selection_view calls this before constructing the actual ListSelectionView. It uses review_needed_count to make the header accurate and standard_popup_hint_line_for_keymap so the footer matches the configured keys.

Call graph: calls 3 internal fn (standard_popup_hint_line_for_keymap, new, review_needed_count); called by 1 (selection_view); 6 external calls (new, default, from, new, format!, vec!).

fn review_needed_count(entry: &HooksListEntry) -> usize

Purpose: Counts how many hooks are new or changed enough to require the user’s attention. This keeps the prompt and the startup decision based on the same rule.

Data flow: It receives a HooksListEntry, looks through its hooks, filters to the hooks that need review, and returns the count.

Call relations: review_is_needed uses this to decide whether the prompt should open. selection_view_params uses the same count to tell the user how many hooks are affected.

Call graph: called by 2 (review_is_needed, selection_view_params).

fn review_is_needed(bypass_hook_trust: bool, entry: &HooksListEntry) -> bool

Purpose: Answers the simple startup question: should the hook review prompt be shown? It respects the bypass option as well as the hook state.

Data flow: It receives a bypass flag and a hook entry. If bypass is enabled, it returns false. Otherwise, it counts review-needed hooks and returns true only when the count is greater than zero.

Call relations: maybe_run_startup_hooks_review calls this before doing any UI work. The tests call it directly to confirm that bypass suppresses the prompt and untrusted hooks trigger it.

Call graph: calls 1 internal fn (review_needed_count); called by 1 (maybe_run_startup_hooks_review).

fn selection_item(name: &str, is_disabled: bool) -> SelectionItem

Purpose: Creates one menu row for the startup prompt. It gives each row a label and controls whether it is disabled.

Data flow: It receives the item name and a disabled flag. It returns a SelectionItem with that name, set to close the selection when chosen, and with the requested disabled state.

Call relations: selection_view_params uses this to create the three prompt choices. When trust-all is running, it passes the disabled flag so all choices become temporarily unavailable.

Call graph: 1 external calls (default).

fn draw_view(tui: &mut Tui, view: &ListSelectionView) -> Result<()>

Purpose: Paints the startup review prompt onto the terminal screen. It clears the current area first so the prompt is shown cleanly.

Data flow: It receives the terminal UI and the selection view. It asks the terminal to draw, clears the available area, computes a height that fits the view and screen, renders the standalone wrapper, and returns success or a drawing error.

Call relations: run_startup_hooks_review_app calls this after creating the view, after terminal resize or redraw events, and after state changes such as starting or failing “trust all.” It is the bridge from prompt state to visible terminal output.

Call graph: called by 1 (run_startup_hooks_review_app); 1 external calls (draw).

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Purpose: Adapts the selection view so the terminal drawing library can render it as a widget. It is a small wrapper around the actual view rendering.

Data flow: It receives a screen rectangle and a text buffer. It asks the underlying ListSelectionView to draw itself into that rectangle and buffer.

Call relations: draw_view renders a StandaloneSelectionView when painting the prompt. This method is called by the terminal widget system during that draw.

Call graph: calls 1 internal fn (render).

fn hook(key: &str, trust_status: HookTrustStatus) -> HookMetadata

Purpose: Builds a fake hook record for tests. This lets the tests create realistic hook data without repeating every field each time.

Data flow: It receives a hook key and a trust status. It fills in a HookMetadata object with fixed test values, uses the key in the hash, and returns the completed hook record.

Call relations: tests::entry calls this to make hooks that look new or changed. Those fake hooks then feed the startup review decision and rendering tests.

Call graph: 2 external calls (test_path_buf, format!).

fn entry() -> HooksListEntry

Purpose: Creates a fake hook-list entry for the test project folder. It contains two hooks that should require review.

Data flow: It creates a test current directory path and a HooksListEntry with two fake hooks, one untrusted and one modified. It returns that entry with no warnings or errors.

Call relations: The review-decision tests and rendering tests use this as their shared sample input. It relies on tests::hook to create the hook metadata.

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

fn render_lines(view: &crate::bottom_pane::ListSelectionView, width: u16) -> String

Purpose: Turns a rendered selection view into plain text for snapshot tests. This makes it easy to compare what the terminal prompt looks like.

Data flow: It receives a ListSelectionView and a width. It asks the view for its height, creates an empty terminal buffer, renders the view into it, reads every character back row by row, trims trailing spaces, and returns the resulting text.

Call relations: The rendering tests call this after building a selection_view. Its output is passed to the snapshot checker so changes to the prompt are visible in tests.

Call graph: calls 2 internal fn (desired_height, render); 2 external calls (empty, new).

fn bypass_hook_trust_suppresses_startup_review()

Purpose: Checks that the bypass option really prevents the startup prompt. This protects the intended behavior for users or modes that intentionally skip hook trust review.

Data flow: It creates the standard fake entry and calls review_is_needed with bypass turned on. It asserts that the result is false.

Call relations: This test calls review_is_needed directly. It confirms the first half of maybe_run_startup_hooks_review’s decision logic without needing to run the full UI.

Call graph: 1 external calls (assert!).

fn untrusted_hooks_need_review_without_bypass()

Purpose: Checks that untrusted or changed hooks trigger the startup prompt when bypass is not enabled. This protects the safety checkpoint.

Data flow: It creates the standard fake entry and calls review_is_needed with bypass turned off. It asserts that the result is true.

Call relations: This test also focuses on review_is_needed. It verifies that the startup flow will enter run_startup_hooks_review_app when risky hooks are present.

Call graph: 1 external calls (assert!).

fn renders_prompt()

Purpose: Checks the normal startup review prompt text and layout. It makes sure the user sees the expected choices and warning message.

Data flow: It creates a dummy app-event channel, uses default key bindings, builds a selection view from the fake hook entry, renders that view to text, and compares it with a saved snapshot.

Call relations: This test calls selection_view the same way the real prompt does, but without starting the full terminal event loop. The snapshot assertion catches accidental changes to the visible prompt.

Call graph: calls 3 internal fn (new, defaults, selection_view); 2 external calls (assert_snapshot!, entry).

fn renders_prompt_with_trust_error()

Purpose: Checks how the prompt looks after “trust all” fails. It ensures the error message is shown as part of the prompt instead of disappearing.

Data flow: It creates a dummy app-event channel, default key bindings, the fake hook entry, and a long sample error message. It builds the selection view with that error, renders it to text, and compares the result with a saved snapshot.

Call relations: This test covers the error path used by run_startup_hooks_review_app after write_hook_trusts fails. It calls selection_view directly so the visual state can be tested in isolation.

Call graph: calls 3 internal fn (new, defaults, selection_view); 2 external calls (assert_snapshot!, entry).

fn clear(&mut self)

Purpose: This resets the memory of which skill-loading warnings are currently active. It is useful when the app wants to allow the same warning to be shown again later.

Data flow: It takes the warning state as it exists now, removes every remembered warning key from it, and returns nothing. Afterward, the state behaves as if no skill warnings have been seen.

Call relations: The tests call this to confirm that clearing the state lets a still-existing skill error be reported again. In normal use, it supports the same warning-tracking flow used by SkillLoadWarningState::newly_active_errors.

fn newly_active_errors(&mut self, errors: &[SkillErrorInfo]) -> Vec<SkillErrorInfo>

Purpose: This compares the latest list of skill-loading errors with the errors that were already active, and returns only the ones that are new. It prevents the interface from repeating the same warning over and over while the same bad skill file remains broken.

Data flow: It receives a list of current skill errors. It turns each error into a key made from the file path and message, compares those keys with the previous set, stores the new current set, and returns cloned error records only for warnings that were not already active.

Call relations: This is the filter that should run before warnings are emitted. The warning display function can then be given just the new errors, so the user sees fresh problems without being spammed by unchanged ones.

Call graph: 3 external calls (new, new, take).

fn emit_skill_load_warnings(app_event_tx: &AppEventSender, errors: &[SkillErrorInfo])

Purpose: This sends visible warning messages when one or more skill files could not be loaded. A skill here is a user-provided capability described by a SKILL.md file, so a bad file means that capability is skipped.

Data flow: It receives an event sender and a list of skill errors. If the list is empty, it does nothing. Otherwise, it sends one summary warning with the count, then sends one warning per error with the file path and error message.

Call relations: The test helper tests::render_skill_load_warning_cells calls it to capture what would appear in the interface. In the app flow, it hands warning cells to the event system so the terminal history can display them.

Call graph: calls 1 internal fn (send); called by 1 (render_skill_load_warning_cells); 6 external calls (new, is_empty, len, InsertHistoryCell, new_warning_event, format!).

fn emit_project_config_warnings(app_event_tx: &AppEventSender, config: &Config)

Purpose: This tells the user when project-local configuration has been disabled because a project is not yet trusted. That matters because local config, hooks, and execution policies can affect what the app is allowed to do.

Data flow: It reads the configuration layer stack, looks for project folders that have a disabled reason, builds a numbered message listing each folder and reason, and sends that message as a warning cell. If no project folders are disabled, it sends nothing.

Call relations: This function is part of startup warning preparation. It takes low-level configuration layer information and hands a readable warning to the app event stream for display.

Call graph: calls 1 internal fn (send); 6 external calls (new, new, InsertHistoryCell, concat!, format!, new_warning_event).

fn emit_system_bwrap_warning(app_event_tx: &AppEventSender, config: &Config)

Purpose: This warns the user if the system sandbox setup may have a problem. The sandbox is a safety boundary that limits what commands can touch on the machine.

Data flow: It reads the current permission profile from the config and asks the sandboxing code whether there is a bubblewrap warning. Bubblewrap is a Linux sandboxing tool. If a warning message is returned, it sends it as a warning cell; otherwise it does nothing.

Call relations: This function sits between the sandboxing subsystem and the terminal UI. It does not decide the warning itself; it asks codex_sandboxing::system_bwrap_warning and passes any result into the app’s event stream.

Call graph: calls 1 internal fn (send); 4 external calls (new, InsertHistoryCell, system_bwrap_warning, new_warning_event).

fn should_show_model_migration_prompt(
    current_model: &str,
    target_model: &str,
    seen_migrations: &BTreeMap<String, String>,
    available_models: &[ModelPreset],
) -> bool

Purpose: This decides whether the app should ask the user to move from one model to another. It avoids showing pointless or repeated upgrade prompts.

Data flow: It receives the current model, the proposed target model, a record of migrations already acknowledged, and the list of available model presets. It returns false if the target is the same as the current model, if this migration was already seen, or if the target is not visible in the model picker. It returns true only when the catalog shows a real upgrade relationship involving these models.

Call relations: handle_model_migration_prompt_if_needed calls this before showing a prompt. This function acts like a gatekeeper, so the later prompt code only runs when there is a meaningful and available migration to offer.

Call graph: called by 1 (handle_model_migration_prompt_if_needed); 1 external calls (iter).

fn migration_prompt_hidden(config: &Config, migration_config_key: &str) -> bool

Purpose: This checks whether a specific migration prompt has been turned off in the user’s configuration. It lets product-specific prompt switches live in config instead of being hard-coded into the prompt flow.

Data flow: It receives the full config and a migration config key. For known keys, it reads the matching boolean setting and treats a missing value as false. For unknown keys, it returns false.

Call relations: handle_model_migration_prompt_if_needed calls this before doing the rest of the migration work. If it returns true, the prompt path stops immediately.

Call graph: called by 1 (handle_model_migration_prompt_if_needed).

fn target_preset_for_upgrade(
    available_models: &'a [ModelPreset],
    target_model: &str,
) -> Option<&'a ModelPreset>

Purpose: This finds the model preset for the proposed upgrade target, but only if that model is meant to be shown to users. A preset is the catalog entry that contains display name, description, and defaults for a model.

Data flow: It receives the available model list and a target model identifier. It searches for a preset with that exact model identifier and with show_in_picker enabled, then returns that preset if found.

Call relations: handle_model_migration_prompt_if_needed uses this after deciding a prompt may be shown. The returned preset supplies user-facing text and the default reasoning effort to apply if the user accepts.

Call graph: called by 1 (handle_model_migration_prompt_if_needed); 1 external calls (iter).

fn apply_accepted_model_migration(
    config: &mut Config,
    app_event_tx: &AppEventSender,
    from_model: String,
    target_model: String,
    target_default_effort: ReasoningEffortConfig,
)

Purpose: This applies a model upgrade after the user accepts the migration prompt. It updates both the live configuration and the saved user preference.

Data flow: It receives mutable config, an event sender, the old model, the target model, and the target model’s default reasoning effort. It records that the prompt was acknowledged, changes config.model and config.model_reasoning_effort, sends events to update the running app, and sends an event to persist the new model selection.

Call relations: handle_model_migration_prompt_if_needed calls this only after the prompt outcome is Accepted. It then hands off to the app event system so both the visible app state and persistent settings are updated.

Call graph: calls 1 internal fn (send); called by 1 (handle_model_migration_prompt_if_needed); 3 external calls (clone, UpdateModel, UpdateReasoningEffort).

fn select_model_availability_nux(
    available_models: &[ModelPreset],
    nux_config: &ModelAvailabilityNuxConfig,
) -> Option<StartupTooltipOverride>

Purpose: This chooses a startup tooltip about model availability, if one should still be shown. NUX means “new user experience,” a short guided message shown only a limited number of times.

Data flow: It receives the model catalog and the stored counts of how often each model’s availability message has been shown. It scans for the first model with an availability message whose count is below the maximum, and returns the model slug plus message. If none qualify, it returns nothing.

Call relations: prepare_startup_tooltip_override calls this to decide whether there is a tooltip worth showing. This function only chooses the candidate; the caller increments and saves the display count.

Call graph: called by 1 (prepare_startup_tooltip_override); 1 external calls (iter).

async fn prepare_startup_tooltip_override(
    config: &mut Config,
    available_models: &[ModelPreset],
    is_first_run: bool,
) -> Option<String>

Purpose: This prepares a one-time startup tooltip message about model availability and records that it was shown. It keeps these messages helpful instead of endlessly repeated.

Data flow: It receives mutable config, available models, and whether this is the first run. It returns nothing if this is the first run or tooltips are disabled. Otherwise it asks select_model_availability_nux for a message, increments that model’s shown count, tries to save the new count to config storage, updates the in-memory config if saving succeeds, and returns the tooltip text.

Call relations: This function builds on select_model_availability_nux. It also uses ConfigEditsBuilder to persist the new count, and logs an error if saving fails while still allowing the tooltip message to be returned.

Call graph: calls 1 internal fn (select_model_availability_nux); 2 external calls (for_config, error!).

async fn handle_model_migration_prompt_if_needed(
    tui: &mut tui::Tui,
    config: &mut Config,
    model: &str,
    app_event_tx: &AppEventSender,
    available_models: &[ModelPreset],
) -> Option

Purpose: This is the main startup flow for offering a model upgrade to the user. It decides whether a prompt is needed, shows it, and reacts to accept, reject, or exit.

Data flow: It receives the terminal UI object, mutable config, the current model name, an event sender, and available model presets. It looks up whether the current model has an upgrade, checks whether the prompt is hidden or already seen, finds the target preset, builds the prompt text, then waits for the user’s choice. Accepting updates the model and saves the choice; rejecting only records that the prompt was acknowledged; exiting returns app exit information.

Call relations: This function coordinates the smaller helpers in this file: migration_prompt_hidden, should_show_model_migration_prompt, target_preset_for_upgrade, and apply_accepted_model_migration. It is the bridge between catalog/config facts, the prompt UI, and the app’s event system.

Call graph: calls 5 internal fn (apply_accepted_model_migration, migration_prompt_hidden, should_show_model_migration_prompt, target_preset_for_upgrade, send); 2 external calls (iter, default).

fn normalize_harness_overrides_for_cwd(
    mut overrides: ConfigOverrides,
    base_cwd: &AbsolutePathBuf,
) -> Result<ConfigOverrides>

Purpose: This turns relative extra writable folder paths into paths based on a chosen working directory. That helps a test or harness configuration mean the same thing no matter where the process was launched from.

Data flow: It receives configuration overrides and a base current working directory. If there are no additional writable roots, it returns the overrides unchanged. Otherwise, it joins each root to the base directory, replaces the list with those normalized paths, and returns the updated overrides.

Call relations: The test tests::normalize_harness_overrides_resolves_relative_add_dirs calls this to verify the behavior. In startup setup, it can prepare override paths before sandbox or permission logic relies on them.

Call graph: calls 1 internal fn (join); called by 1 (normalize_harness_overrides_resolves_relative_add_dirs); 1 external calls (with_capacity).

fn normalize_harness_overrides_resolves_relative_add_dirs() -> Result<()>

Purpose: This test proves that a relative writable root is resolved under the provided base directory. It protects against accidentally treating such paths as relative to some other process location.

Data flow: It creates a temporary directory, creates a base folder inside it, builds overrides containing the relative path rel, runs normalize_harness_overrides_for_cwd, and checks that the result is base/rel.

Call relations: This test directly exercises normalize_harness_overrides_for_cwd. If that helper changes and stops normalizing paths correctly, this test should fail.

Call graph: calls 1 internal fn (normalize_harness_overrides_for_cwd); 5 external calls (default, assert_eq!, create_dir_all, tempdir, vec!).

fn skill_error(path: &str, message: &str) -> SkillErrorInfo

Purpose: This small test helper creates a SkillErrorInfo value from simple string inputs. It keeps the skill-warning tests short and readable.

Data flow: It receives a path string and a message string. It converts the path into a PathBuf, copies the message into an owned string, and returns a SkillErrorInfo record.

Call relations: Several tests call this helper before exercising SkillLoadWarningState. It supplies consistent fake errors without repeating struct-building code.

Call graph: 1 external calls (from).

fn render_line_text(line: &Line<'static>) -> String

Purpose: This test helper turns a rendered terminal line into plain text. It strips away styling so tests can compare the words the user would see.

Data flow: It receives a ratatui Line, reads each span of text inside it, concatenates the span contents, and returns one plain string.

Call relations: tests::render_skill_load_warning_cells uses this after warning cells are rendered. It lets the snapshot test compare human-readable warning output.

fn render_skill_load_warning_cells(errors: &[SkillErrorInfo]) -> String

Purpose: This test helper runs the skill warning emitter and captures the rendered warning text. It simulates the app event path without needing the full terminal app.

Data flow: It receives a list of skill errors, creates an in-memory event channel, wraps the sender in AppEventSender, calls emit_skill_load_warnings, then drains inserted history cells from the receiver. It renders their display lines and joins them into a single string.

Call relations: This helper calls emit_skill_load_warnings and is used by the repeated warning snapshot test. It connects the event-producing code to the rendered text that a user would actually see.

Call graph: calls 2 internal fn (emit_skill_load_warnings, new); 2 external calls (new, unbounded_channel).

fn skill_load_warning_state_suppresses_repeated_active_errors()

Purpose: This test checks that the same active skill error is reported once, not repeatedly. It confirms the anti-spam behavior of the warning state.

Data flow: It creates a fresh SkillLoadWarningState and one fake error. The first call returns that error as new; the second call with the same error returns an empty list.

Call relations: This test exercises SkillLoadWarningState::newly_active_errors through its public behavior. It supports the startup warning flow by proving repeated active errors are filtered out.

Call graph: 3 external calls (assert_eq!, default, skill_error).

fn skill_load_warning_state_reemits_after_error_clears()

Purpose: This test checks that an error can be shown again if it disappears and later returns. That is important because a returning error may represent a fresh problem the user should notice.

Data flow: It creates a warning state and a fake error. It reports the error once, then calls with an empty list to mark it cleared, then calls with the same error again and expects it to be returned as new.

Call relations: This test focuses on SkillLoadWarningState::newly_active_errors. It proves the state tracks currently active errors, not every error ever seen forever.

Call graph: 3 external calls (assert_eq!, default, skill_error).

fn skill_load_warning_state_displays_new_message_for_active_path()

Purpose: This test checks that a changed error message for the same file is treated as a new warning. A different message may tell the user about a different problem in the same skill file.

Data flow: It creates two fake errors with the same path but different messages. After reporting the first, it reports the second and expects the second to be returned as newly active.

Call relations: This test verifies the key used by SkillLoadWarningState::newly_active_errors includes both path and message. That supports accurate warning updates when the reason changes.

Call graph: 3 external calls (assert_eq!, default, skill_error).

fn skill_load_warning_state_clear_allows_active_error_again()

Purpose: This test confirms that clearing the warning state makes an already-active error eligible to be shown again. It validates the reset behavior.

Data flow: It creates a warning state and one fake error. The first call returns the error, the second suppresses it, then clear is called, and the next call returns the error again.

Call relations: This test uses SkillLoadWarningState::clear together with SkillLoadWarningState::newly_active_errors. It proves the manual reset path works.

Call graph: 3 external calls (assert_eq!, default, skill_error).

fn repeated_active_skill_load_warning_renders_once()

Purpose: This snapshot test checks the final text shown for a repeated active skill warning. It makes sure the user sees the warning once, with the expected summary and file-specific message.

Data flow: It creates a warning state and one fake skill error. It asks for newly active errors twice, renders warnings for both results, drops empty output, joins what remains, and compares it to a saved expected snapshot.

Call relations: This test combines SkillLoadWarningState::newly_active_errors with tests::render_skill_load_warning_cells, which calls emit_skill_load_warnings. It verifies the full mini-flow from deduplication to displayed warning text.

Call graph: 5 external calls (assert_snapshot!, from_ref, default, render_skill_load_warning_cells, skill_error).

fn experimental_tooltips() -> Vec<&'static str>

Purpose: Collects announcement text for features that are marked as experimental. This lets newly introduced features add startup messages without putting every message directly in this file.

Data flow: It reads the global feature list, looks at each feature's stage, keeps only the stages that provide an experimental announcement, and returns those messages as a list of text snippets.

Call relations: It feeds the ALL_TOOLTIPS startup list. When that list is built, the normal tooltip text is combined with these feature-driven tips so pick_tooltip can choose from both.

fn get_tooltip(plan: Option<PlanType>, fast_mode_enabled: bool) -> Option<String>

Purpose: Chooses the single tooltip, promotion, or announcement to show when Codex starts. It uses the user's plan and whether fast mode is already enabled to avoid showing irrelevant messages.

Data flow: It receives an optional account plan and a true-or-false flag for fast mode. It first checks for a cached remote announcement. If one matches, it returns that. If not, it uses random chance and plan rules to choose a paid-plan promo, a free/Go promo, a generic app promo, or finally a random built-in tooltip. The result is either a message string or no message.

Call relations: This is the top-level picker used by the startup UI. It asks announcement::fetch_announcement_tip for high-priority remote announcements, calls pick_paid_tooltip for paid-plan promotion choices, and calls pick_tooltip when it falls back to the general random pool.

Call graph: calls 2 internal fn (pick_paid_tooltip, pick_tooltip); 3 external calls (fetch_announcement_tip, matches!, rng).

fn paid_app_tooltip() -> Option<&'static str>

Purpose: Returns the Codex App promotion only on operating systems where that app promotion should be shown. This prevents users on unsupported platforms from seeing a misleading app prompt.

Data flow: It checks compile-time operating system flags. On macOS or Windows it returns the app promotion text; otherwise it returns nothing.

Call relations: It is a small helper for pick_paid_tooltip. The paid-tooltip tests also call it to build the expected result for the current operating system.

Call graph: called by 3 (pick_paid_tooltip, paid_tooltip_pool_rotates_between_promos, paid_tooltip_pool_skips_fast_when_fast_mode_is_enabled).

fn pick_paid_tooltip(
    rng: &mut R,
    fast_mode_enabled: bool,
) -> Option<&'static str>

Purpose: Chooses the special promotional tooltip for paid users. It splits attention between the Codex App and fast mode, but stops advertising fast mode once the user already has it enabled.

Data flow: It receives a random number generator and a fast-mode flag. If fast mode is already on, it tries to return the app promo. If fast mode is off, it flips a random yes/no choice: one side picks the app promo, the other side picks the fast-mode promo. The output is a message or nothing if the app promo is not suitable for this operating system.

Call relations: get_tooltip calls this when the user is on a paid or team-like plan. The tests call it repeatedly with seeded random generators to prove it can rotate between promos and that it suppresses the fast-mode promo when needed.

Call graph: calls 1 internal fn (paid_app_tooltip); called by 3 (get_tooltip, paid_tooltip_pool_rotates_between_promos, paid_tooltip_pool_skips_fast_when_fast_mode_is_enabled); 1 external calls (random_bool).

fn pick_tooltip(rng: &mut R) -> Option<&'static str>

Purpose: Selects one random message from the full built-in tooltip pool. This is the general fallback when no targeted announcement or promotion is chosen.

Data flow: It receives a random number generator. If there are no available tips, it returns nothing. Otherwise it chooses a random index in the tooltip list and returns the message at that position.

Call relations: get_tooltip calls this for the small chance of showing a general tip. A reproducibility test also calls it with a seeded random generator to confirm the same seed gives the same result.

Call graph: called by 2 (get_tooltip, random_tooltip_is_reproducible_with_seed); 1 external calls (random_range).

fn prewarm()

Purpose: Starts loading the remote announcement in the background before it is needed. This keeps startup responsive because the main program does not wait on the network.

Data flow: It takes no input. It starts a background thread that initializes the shared announcement cache. It does not return the announcement directly; it only begins the work.

Call relations: Startup code can call this early. Later, announcement::fetch_announcement_tip checks whether the background work has completed and uses the cached text if it is available.

Call graph: 1 external calls (spawn).

fn fetch_announcement_tip(plan: Option<PlanType>) -> Option<String>

Purpose: Returns a remote announcement if one has already been downloaded and matches the current user. It deliberately does not wait if the background download is still running.

Data flow: It receives the user's optional plan. It reads the one-time announcement cache. If the cache contains downloaded TOML text, it parses and filters that text for the plan and returns the chosen announcement content. If the cache is empty, unfinished, invalid, or has no match, it returns nothing.

Call relations: get_tooltip calls this first because remote announcements have priority over ordinary tips. It hands the raw downloaded text to announcement::parse_announcement_tip_toml so the detailed matching rules are applied in one place.

fn current() -> Self

Purpose: Identifies which operating system this build of Codex is running on. Announcement filtering uses this so OS-specific messages only appear where they make sense.

Data flow: It reads compile-time operating system flags. It returns Macos for macOS builds, Windows for Windows builds, and Linux otherwise.

Call relations: The announcement module stores this as its current operating system value. announcement::parse_announcement_tip_toml compares announcement target operating systems against it when deciding whether a remote message applies.

Call graph: 1 external calls (cfg!).

fn init_announcement_tip_in_thread() -> Option<String>

Purpose: Runs the blocking announcement download in a separate thread and converts its result into the cache value. This wrapper keeps the one-time cache initialization isolated from the network call.

Data flow: It takes no input. It starts a thread that performs the actual download, waits for that thread to finish, and returns the downloaded text if the thread succeeded and the download produced text.

Call relations: announcement::prewarm uses this as the initializer for the announcement cache. It delegates the actual HTTP work to announcement::blocking_init_announcement_tip.

Call graph: 1 external calls (spawn).

fn blocking_init_announcement_tip() -> Option<String>

Purpose: Downloads the remote announcement file from GitHub. It is intentionally short-timeout and fail-soft, so a network problem does not break Codex startup.

Data flow: It creates a blocking HTTP client with proxy detection disabled, requests the announcement URL with a two-second timeout, checks that the response status is successful, and returns the response body as text. Any setup, network, HTTP, or text-reading failure becomes no result.

Call relations: announcement::init_announcement_tip_in_thread calls this inside a worker thread. The downloaded text later flows through the shared cache into announcement::fetch_announcement_tip and then into the main get_tooltip decision.

Call graph: 2 external calls (from_millis, builder).

fn parse_announcement_tip_toml(
        text: &str,
        plan: Option<PlanType>,
    ) -> Option<String>

Purpose: Reads a remote announcement document and picks the last announcement that applies right now. It filters by date, CLI version, target app, user plan, and operating system.

Data flow: It receives TOML text and an optional plan. It parses the text either as a document with an announcements list or as a plain list. For each raw announcement, it builds a validated AnnouncementTip, checks whether it matches today's date, the current CLI version, the CLI app, the plan, and the current operating system, and remembers the latest matching message. It returns that message or nothing.

Call relations: announcement::fetch_announcement_tip calls this after retrieving cached remote text. It relies on announcement::AnnouncementTip::from_raw to validate each entry, then uses version_matches and date_matches to apply the remaining rules. Many tests exercise this function because it is the heart of remote announcement selection.

Call graph: 2 external calls (now, from_raw).

fn from_raw(raw: AnnouncementTipRaw) -> Option<Self>

Purpose: Turns a loosely parsed announcement entry into a validated announcement that the program can safely compare. Bad dates, bad version patterns, empty content, and unknown target names are rejected.

Data flow: It receives a raw announcement with strings and optional fields. It trims the content, parses date strings into date values, compiles the version pattern into a regular expression, normalizes the target app name, and rejects entries with unknown plan or operating system targets. It returns a cleaned AnnouncementTip or nothing if validation fails.

Call relations: announcement::parse_announcement_tip_toml calls this for every announcement entry before applying match rules. Its output is then checked by version_matches and date_matches.

Call graph: 2 external calls (parse_from_str, new).

fn version_matches(&self, version: &str) -> bool

Purpose: Checks whether an announcement applies to a particular Codex CLI version. If no version rule was supplied, the announcement applies to all versions.

Data flow: It receives a version string. If the announcement has a regular expression, it tests the version string against that pattern. If there is no pattern, it returns true.

Call relations: announcement::parse_announcement_tip_toml uses this while scanning remote announcements. It is one of the filters that decides whether a message is eligible to be shown.

fn date_matches(&self, today: NaiveDate) -> bool

Purpose: Checks whether an announcement is active on a given date. This lets remote messages have a start date and an end date.

Data flow: It receives today's date. If the announcement has a start date and today is before it, it returns false. If it has an end date and today is on or after that end date, it returns false. Otherwise it returns true.

Call relations: announcement::parse_announcement_tip_toml calls this after converting raw entries into validated announcements. Together with version, plan, app, and operating system checks, it decides whether an announcement can be shown.

fn random_tooltip_returns_some_tip_when_available()

Purpose: Confirms that the random tooltip picker can return a message when the tooltip pool is populated. This protects against accidentally emptying the built-in tip list.

Data flow: It creates a predictable random number generator from a fixed seed, calls the random tooltip picker, and checks that the result is present.

Call relations: This test exercises pick_tooltip indirectly through the module's internal test access. It supports the fallback path used by get_tooltip.

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

fn random_tooltip_is_reproducible_with_seed()

Purpose: Confirms that using the same random seed produces the same tooltip choice. This makes the random behavior testable and repeatable.

Data flow: It creates one seeded random generator and records the tooltip selected from it. Then it creates another generator with the same seed, picks again, and checks that both results are equal.

Call relations: This test calls pick_tooltip directly. It verifies the general random-tip path that get_tooltip uses as a fallback.

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

fn paid_tooltip_pool_rotates_between_promos()

Purpose: Checks that paid users can see both paid promotional options when fast mode is not already enabled. This guards the intended split between app promotion and fast-mode promotion.

Data flow: It tries many seeded random generators, calls pick_paid_tooltip with fast mode off, stores every result it sees, and compares that set with the expected app-promo and fast-promo choices for the current operating system.

Call relations: This test calls both pick_paid_tooltip and paid_app_tooltip. It protects the paid-user branch used by get_tooltip.

Call graph: calls 2 internal fn (paid_app_tooltip, pick_paid_tooltip); 4 external calls (seed_from_u64, assert_eq!, from, new).

fn paid_tooltip_pool_skips_fast_when_fast_mode_is_enabled()

Purpose: Checks that users who already enabled fast mode are not shown the fast-mode advertisement. This prevents a stale or annoying promotion.

Data flow: It tries several seeded random generators, calls pick_paid_tooltip with fast mode on, gathers the results, and checks that only the app-promo option appears and the fast-mode message does not.

Call relations: This test calls pick_paid_tooltip and paid_app_tooltip. It verifies the fast-mode suppression rule inside the paid-user path of get_tooltip.

Call graph: calls 2 internal fn (paid_app_tooltip, pick_paid_tooltip); 5 external calls (seed_from_u64, assert!, assert_eq!, from, new).

fn announcement_tip_toml_picks_last_matching()

Purpose: Confirms that when several remote announcements match, the last matching one wins. This lets the remote file override earlier general messages with later, more specific ones.

Data flow: It builds sample TOML with multiple announcements, including earlier matches and non-matches, parses it, and checks that the returned message is the later matching entry.

Call relations: This test focuses on announcement::parse_announcement_tip_toml, the selector used by announcement::fetch_announcement_tip before get_tooltip shows a remote announcement.

Call graph: 1 external calls (assert_eq!).

fn announcement_tip_toml_picks_no_match()

Purpose: Confirms that no remote announcement is returned when every entry is expired, version-mismatched, or meant for another app. This prevents irrelevant remote messages from appearing.

Data flow: It builds sample TOML where each announcement fails a different rule, parses it with no plan, and checks that the result is empty.

Call relations: This test exercises the filtering rules inside announcement::parse_announcement_tip_toml, especially date, version, and target-app checks.

Call graph: 1 external calls (assert_eq!).

fn announcement_tip_toml_bad_deserialization()

Purpose: Confirms that malformed announcement TOML is ignored safely. A bad remote file should not crash Codex or show nonsense.

Data flow: It supplies TOML where the content field has the wrong type, asks the parser to read it, and checks that no announcement is returned.

Call relations: This test protects the error-handling path in announcement::parse_announcement_tip_toml, which is reached through announcement::fetch_announcement_tip when remote text is available.

Call graph: 1 external calls (assert_eq!).

fn announcement_tip_toml_parse_comments()

Purpose: Confirms that a realistic announcement file with comments can be parsed and that a valid later announcement is selected. This matches how maintainers are expected to write the remote file.

Data flow: It provides a commented TOML example with one version-limited announcement and one simple announcement, parses it, and checks that the simple valid message is returned.

Call relations: This test exercises announcement::parse_announcement_tip_toml using a document shape close to the production remote announcement file.

Call graph: 1 external calls (assert_eq!).

fn announcement_tip_toml_matches_target_plan_type()

Purpose: Checks that plan-specific announcements are shown only to users on matching plans, while general announcements remain available to everyone. This keeps messaging relevant to account type.

Data flow: It builds TOML with a general announcement plus pro/enterprise and free-specific announcements. It parses the same text with different plan inputs and checks that each plan receives the expected message.

Call relations: This test verifies the plan filtering inside announcement::parse_announcement_tip_toml, which is fed by announcement::fetch_announcement_tip using the plan passed into get_tooltip.

Call graph: 1 external calls (assert_eq!).

fn announcement_tip_toml_rejects_unknown_target_plan_type()

Purpose: Confirms that an announcement with an unrecognized plan target is ignored. This protects users from messages caused by typos in the remote file.

Data flow: It provides TOML with a valid general announcement and another announcement using a misspelled plan name. It parses the text and checks that only the general announcement is selected.

Call relations: This test covers validation performed by announcement::AnnouncementTip::from_raw as part of the parsing flow in announcement::parse_announcement_tip_toml.

Call graph: 1 external calls (assert_eq!).

fn announcement_tip_toml_matches_target_os()

Purpose: Checks that operating-system-specific announcements match the platform running the test. This prevents, for example, a Windows-only message from appearing on macOS or Linux.

Data flow: It builds TOML with separate Linux, macOS, and Windows announcements, computes which one should match the current build, parses the TOML, and checks that the expected message is returned.

Call relations: This test exercises the operating system filtering in announcement::parse_announcement_tip_toml, which depends on announcement::TargetOs::current through the module's current OS constant.

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

fn announcement_tip_toml_rejects_unknown_target_os()

Purpose: Confirms that an announcement with an unrecognized operating system target is ignored. This keeps remote-file typos from producing accidental matches.

Data flow: It provides TOML with a valid all-platform announcement and another announcement using an invalid operating system name. It parses the text and checks that the valid all-platform message is returned.

Call relations: This test covers the operating-system validation in announcement::AnnouncementTip::from_raw, which is used during announcement::parse_announcement_tip_toml.

Call graph: 1 external calls (assert_eq!).

async fn run_update_prompt_if_needed(
    tui: &mut Tui,
    config: &Config,
) -> Result<UpdatePromptOutcome>

Purpose: This is the top-level routine for deciding whether the update prompt should appear. It checks whether an update is available, displays the prompt if needed, waits for the user’s choice, and returns what the rest of the app should do next.

Data flow: It receives the terminal interface and the user configuration. It asks the update system for a newer version and asks the update-action code what command could perform the upgrade. If either answer is missing, it returns “continue.” Otherwise it draws the prompt, reads terminal events, updates the screen as keys arrive, and finally returns either “run this update action” or “continue.” If the user chose not to be reminded about this version, it also tries to save that dismissal in the configuration-related update state.

Call relations: The main terminal app calls this during startup through run_ratatui_app. This function pulls together updates::get_upgrade_version_for_popup, crate::update_action::get_update_action, UpdatePromptScreen::new, terminal drawing, and the TUI event stream. It hands keyboard events to UpdatePromptScreen::handle_key and uses the finished screen state to decide what outcome to return.

Call graph: calls 3 internal fn (get_update_action, new, get_upgrade_version_for_popup); called by 1 (run_ratatui_app); 7 external calls (draw, event_stream, frame_requester, pin!, error!, RunUpdate, dismiss_version).

fn new(
        request_frame: FrameRequester,
        latest_version: String,
        update_action: UpdateAction,
    ) -> Self

Purpose: This builds the in-memory state for the update prompt before it is drawn. It records what version is available, what update command would be used, and which menu option starts highlighted.

Data flow: It takes a frame requester, the latest version string, and an update action. It also reads the current app version from the build-time package version. It returns a fresh prompt screen with “Update now” highlighted and no final selection yet.

Call relations: run_update_prompt_if_needed uses this when the real prompt is needed. The test helper tests::new_prompt also uses it to create predictable screens for rendering and keyboard tests.

Call graph: called by 2 (run_update_prompt_if_needed, new_prompt); 1 external calls (env!).

fn handle_key(&mut self, key_event: KeyEvent)

Purpose: This translates a keyboard press into a prompt action. It lets the user move through the choices, confirm a choice, or cancel the prompt in familiar terminal ways.

Data flow: It receives one key event. Key-release events are ignored so one press is not processed twice. Ctrl-C and Ctrl-D choose “skip.” Up or k moves the highlight to the previous option, Down or j moves to the next option, number keys select a specific row, Enter selects the highlighted row, and Escape skips. The screen’s highlighted item or final selection may change.

Call relations: The event loop in run_update_prompt_if_needed calls this whenever the TUI reports a key event. It delegates movement to UpdateSelection::next and UpdateSelection::prev, and delegates screen-state changes to set_highlight and select so redraw requests happen consistently.

Call graph: calls 4 internal fn (select, set_highlight, next, prev); 1 external calls (matches!).

fn set_highlight(&mut self, highlight: UpdateSelection)

Purpose: This changes which menu option is visually highlighted. It also asks the terminal UI to redraw, but only when the highlight actually changes.

Data flow: It receives the option that should become highlighted. If that option differs from the current one, it updates the screen state and schedules a new frame so the user can see the new highlight. It returns nothing.

Call relations: UpdatePromptScreen::handle_key calls this after navigation keys. It uses the FrameRequester stored on the screen to request a redraw from the larger TUI system.

Call graph: calls 1 internal fn (schedule_frame); called by 1 (handle_key).

fn select(&mut self, selection: UpdateSelection)

Purpose: This records the user’s final choice. Once this is called, the prompt is considered finished.

Data flow: It receives the chosen update option. It makes that option both the highlighted row and the saved final selection, then schedules a redraw so the chosen state can be reflected before the prompt exits. It returns nothing.

Call relations: UpdatePromptScreen::handle_key calls this when the user confirms, presses a number shortcut, cancels, or sends Ctrl-C/Ctrl-D. The outer prompt loop later notices the selection through is_done and selection.

Call graph: calls 1 internal fn (schedule_frame); called by 1 (handle_key).

fn is_done(&self) -> bool

Purpose: This answers whether the user has made a final choice. The event loop uses it to know when to stop waiting for input.

Data flow: It reads the screen’s stored selection. If there is a saved selection, it returns true; otherwise it returns false. It does not change anything.

Call relations: run_update_prompt_if_needed checks this repeatedly while waiting for terminal events. Once it becomes true, that outer function leaves the prompt loop and decides the final outcome.

fn selection(&self) -> Option<UpdateSelection>

Purpose: This returns the final choice the user made, if any. It is used after the prompt ends to decide whether to update, skip, or remember a dismissal.

Data flow: It reads the optional selection stored in the screen and returns it. If no choice has been made, the result is empty. It does not change screen state.

Call relations: After the event loop finishes, run_update_prompt_if_needed calls this to convert the user’s choice into an UpdatePromptOutcome for the rest of the application.

fn latest_version(&self) -> &str

Purpose: This provides the latest version string stored on the prompt. It is mainly used when saving the user’s “do not remind me about this version” choice.

Data flow: It reads the prompt’s latest-version text and returns it as a borrowed string. It does not allocate new data or change anything.

Call relations: run_update_prompt_if_needed uses this when calling the update system to dismiss the currently offered version.

fn next(self) -> Self

Purpose: This gives the next menu option when the user moves downward. It wraps around from the last option back to the first, like a circular menu.

Data flow: It receives the current option and returns the option below it. “Update now” becomes “Skip,” “Skip” becomes “Skip until next version,” and the last option becomes “Update now.” It changes no stored state by itself.

Call relations: UpdatePromptScreen::handle_key calls this for Down and j key navigation, then passes the result to set_highlight.

Call graph: called by 1 (handle_key).

fn prev(self) -> Self

Purpose: This gives the previous menu option when the user moves upward. It wraps around from the first option to the last.

Data flow: It receives the current option and returns the option above it. “Update now” wraps to “Skip until next version,” while the other options move one row upward. It changes no stored state by itself.

Call relations: UpdatePromptScreen::handle_key calls this for Up and k key navigation, then passes the result to set_highlight.

Call graph: called by 1 (handle_key).

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Purpose: This draws the update prompt into the terminal screen buffer. It turns the prompt’s state into visible text, colors, spacing, menu rows, and a release-notes link.

Data flow: It receives the available screen area and the terminal buffer to draw into. It clears the area, builds a vertical column of lines, inserts the current and latest versions, shows the update command, marks which menu row is highlighted, adds an Enter-key hint, renders the column, and marks the underlined release-notes URL as a terminal hyperlink. The output is not a return value; it is the changed terminal buffer.

Call relations: The TUI drawing code calls this through the WidgetRef interface whenever run_update_prompt_if_needed draws or redraws the prompt. It uses helpers such as selection_option_row, command_str, and hyperlink marking to keep the visual style consistent with the rest of the terminal UI.

Call graph: calls 5 internal fn (tlbr, new, selection_option_row, mark_underlined_hyperlink, command_str); 3 external calls (from, format!, vec!).

fn new_prompt() -> UpdatePromptScreen

Purpose: This test helper creates a standard update prompt for the unit tests. It avoids repeating the same setup in every test.

Data flow: It creates a dummy frame requester, uses a fake latest version of 9.9.9, and chooses a known update action. It returns a ready-to-test UpdatePromptScreen.

Call relations: All the tests in this module call this helper before checking rendering or keyboard behavior. It calls UpdatePromptScreen::new, just like the real prompt flow does, but with test-friendly inputs.

Call graph: calls 2 internal fn (test_dummy, new).

fn update_prompt_snapshot()

Purpose: This test checks what the update prompt looks like when rendered. A snapshot test compares the terminal output against a saved expected version.

Data flow: It builds a prompt, creates a fake 80-by-12 terminal, draws the screen into that terminal, and compares the resulting terminal contents with the stored snapshot. It changes only test-local objects.

Call relations: This test uses tests::new_prompt to get the screen and then exercises UpdatePromptScreen::render_ref indirectly through terminal drawing. It protects the prompt layout from accidental visual changes.

Call graph: calls 1 internal fn (new); 3 external calls (assert_snapshot!, new, new_prompt).

fn update_prompt_confirm_selects_update()

Purpose: This test confirms that pressing Enter on the default prompt chooses “Update now.” It proves the default highlighted option is actionable.

Data flow: It creates a prompt, sends an Enter key event, and then checks that the prompt is done and that the saved selection is UpdateNow.

Call relations: The test uses tests::new_prompt and drives UpdatePromptScreen::handle_key. It verifies the path that the real event loop would use when a user accepts the update immediately.

Call graph: 4 external calls (new, assert!, assert_eq!, new_prompt).

fn update_prompt_dismiss_option_leaves_prompt_in_normal_state()

Purpose: This test checks that moving down once and pressing Enter chooses the temporary skip option. It confirms that normal dismissal does not accidentally trigger an update.

Data flow: It creates a prompt, sends a Down key event to move the highlight to “Skip,” sends Enter, and checks that the prompt is finished with NotNow selected.

Call relations: The test exercises UpdatePromptScreen::handle_key, including its use of menu navigation and selection. It mirrors what happens when the outer prompt loop receives those same key events from a real user.

Call graph: 4 external calls (new, assert!, assert_eq!, new_prompt).

fn update_prompt_dont_remind_selects_dismissal()

Purpose: This test checks that the third menu option is reachable and records the “skip until next version” choice. That choice is important because it leads to persisting a dismissal in the real flow.

Data flow: It creates a prompt, sends two Down key events to move to the third row, sends Enter, and checks that the prompt is done with DontRemind selected.

Call relations: The test uses tests::new_prompt and UpdatePromptScreen::handle_key. It verifies the user path that later causes run_update_prompt_if_needed to call the update dismissal code.

Call graph: 4 external calls (new, assert!, assert_eq!, new_prompt).

fn update_prompt_ctrl_c_skips_update()

Purpose: This test ensures Ctrl-C behaves as a safe cancel rather than as an update confirmation. In terminal programs, users often press Ctrl-C to back out, so this behavior matters.

Data flow: It creates a prompt, sends a Ctrl-C key event, and checks that the prompt is finished with NotNow selected.

Call relations: The test drives the same UpdatePromptScreen::handle_key shortcut path that the real prompt uses when the TUI event stream reports Ctrl-C.

Call graph: 5 external calls (Char, new, assert!, assert_eq!, new_prompt).

fn update_prompt_navigation_wraps_between_entries()

Purpose: This test checks that menu navigation wraps around at the top and bottom. That makes the small three-item menu feel predictable and prevents the highlight from getting stuck.

Data flow: It creates a prompt with “Update now” highlighted, sends Up and checks that the highlight moved to the last option, then sends Down and checks that it returned to the first option.

Call relations: The test exercises UpdatePromptScreen::handle_key, which in turn uses UpdateSelection::prev and UpdateSelection::next. It confirms the circular-menu behavior used during real keyboard navigation.

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

fn verb(self) -> &'static str

Purpose: Returns the action word to show in the prompt, such as "resume" or "fork". This keeps the same screen reusable for both cases.

Data flow: It starts with a CwdPromptAction value. It matches that value to the right plain English verb. It returns a short text string used in the prompt title.

Call relations: When the prompt is drawn, render_ref asks this function for the right verb so the message says what the user is actually doing.

Call graph: called by 1 (render_ref).

fn past_participle(self) -> &'static str

Purpose: Returns the past-tense wording for the action, such as "resumed" or "forked". This is used in the explanatory text about the session directory.

Data flow: It receives the current action value. It converts that value into a short text phrase. The phrase is returned for display on screen.

Call relations: The drawing code in render_ref calls this while building the help text, so the explanation matches whether the session is being resumed or forked.

Call graph: called by 1 (render_ref).

fn next(self) -> Self

Purpose: Moves the menu highlight to the other directory choice. Because there are only two choices, moving next just toggles between them.

Data flow: It receives the currently highlighted choice. If it is Current, it returns Session; if it is Session, it returns Current.

Call relations: CwdPromptScreen::handle_key calls this when the user presses Down or j, so keyboard navigation changes the highlighted row.

Call graph: called by 1 (handle_key).

fn prev(self) -> Self

Purpose: Moves the menu highlight to the previous directory choice. With only two choices, this behaves the same as moving next: it switches to the other option.

Data flow: It receives the currently highlighted choice. It returns the opposite choice. It does not change anything by itself.

Call relations: CwdPromptScreen::handle_key calls this when the user presses Up or k, so the user can navigate the menu in either direction.

Call graph: called by 1 (handle_key).

async fn run_cwd_selection_prompt(
    tui: &mut Tui,
    action: CwdPromptAction,
    current_cwd: &Path,
    session_cwd: &Path,
) -> Result<CwdPromptOutcome>

Purpose: Runs the full working-directory prompt from start to finish. It draws the prompt, listens for terminal events, and returns either the user's directory choice or an exit result.

Data flow: It receives the terminal UI object, the action wording to use, and two filesystem paths: the current directory and the session directory. It turns the paths into display text, creates a CwdPromptScreen, draws it, then reads events from the terminal until the screen reports that it is done. At the end it returns Exit if the user cancelled, otherwise it returns the selected directory choice, defaulting to the session directory if needed.

Call relations: This is called by resolve_cwd_for_resume_or_fork when the larger resume-or-fork flow needs the user's decision. It creates the screen with CwdPromptScreen::new, sends keyboard events into CwdPromptScreen::handle_key, and redraws the screen whenever the terminal asks for a draw or resize.

Call graph: calls 1 internal fn (new); called by 1 (resolve_cwd_for_resume_or_fork); 6 external calls (display, draw, event_stream, frame_requester, pin!, Selection).

fn new(
        request_frame: FrameRequester,
        action: CwdPromptAction,
        current_cwd: String,
        session_cwd: String,
    ) -> Self

Purpose: Creates a fresh prompt screen with all the text and starting state needed to ask the question. The session directory starts highlighted because it is the default choice.

Data flow: It receives a frame requester, the action type, and the two directory strings to show. It stores them in a new CwdPromptScreen, sets the highlighted option to Session, and records that no selection or exit has happened yet. It returns the ready-to-render screen state.

Call relations: run_cwd_selection_prompt uses this to start the real prompt. The tests also use it, through tests::new_prompt or directly, to create predictable screens for snapshots and key-behavior checks.

Call graph: called by 3 (run_cwd_selection_prompt, cwd_prompt_fork_snapshot, new_prompt).

fn handle_key(&mut self, key_event: KeyEvent)

Purpose: Interprets one keyboard event and updates the prompt state. This is where keys like Enter, Escape, arrows, number keys, Ctrl-C, and Ctrl-D get their meaning.

Data flow: It receives a key event. It ignores key-release events, treats Ctrl-C and Ctrl-D as an exit request, moves the highlight for navigation keys, chooses an option for number keys or Enter, and chooses the session directory for Escape. When the screen changes, it asks the terminal to draw another frame.

Call relations: The event loop in run_cwd_selection_prompt calls this whenever a key event arrives. It delegates small pieces of work to CwdSelection::next, CwdSelection::prev, CwdPromptScreen::set_highlight, and CwdPromptScreen::select.

Call graph: calls 5 internal fn (select, set_highlight, next, prev, schedule_frame); 1 external calls (matches!).

fn set_highlight(&mut self, highlight: CwdSelection)

Purpose: Changes which menu item is visually highlighted. It avoids unnecessary redraws if the requested highlight is already active.

Data flow: It receives the desired highlighted choice. If that choice differs from the current one, it updates the stored highlight and schedules a new frame so the screen can show the change. It returns nothing.

Call relations: CwdPromptScreen::handle_key calls this after navigation keys decide the next highlighted option. It then uses the frame requester to make sure the user sees the updated highlight.

Call graph: calls 1 internal fn (schedule_frame); called by 1 (handle_key).

fn select(&mut self, selection: CwdSelection)

Purpose: Records the user's final directory choice. It also moves the highlight to that choice so the visual state and stored decision agree.

Data flow: It receives the chosen CwdSelection. It stores that choice as both the highlighted row and the final selection, then schedules a redraw. After this, is_done will report that the prompt can finish.

Call relations: CwdPromptScreen::handle_key calls this when the user presses Enter, Escape, or a direct number key. The outer loop in run_cwd_selection_prompt later reads the stored choice with selection.

Call graph: calls 1 internal fn (schedule_frame); called by 1 (handle_key).

fn is_done(&self) -> bool

Purpose: Answers whether the prompt should stop waiting for input. It is done once the user has selected an option or asked to exit.

Data flow: It reads the screen's should_exit flag and the optional stored selection. If either says the interaction is finished, it returns true; otherwise it returns false.

Call relations: run_cwd_selection_prompt checks this during its event loop to know whether to keep listening for terminal events or return an outcome.

fn selection(&self) -> Option<CwdSelection>

Purpose: Returns the directory choice that has been made, if any. Other code uses this after the prompt finishes to learn what the user picked.

Data flow: It reads the screen's stored optional selection. It returns that value unchanged, either Some(Session), Some(Current), or None if no choice was recorded.

Call relations: After run_cwd_selection_prompt leaves its loop, it calls this to turn the screen state into a CwdPromptOutcome. Several tests also call it to check that key presses choose the expected option.

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Purpose: Draws the prompt into the terminal screen buffer. It turns the current prompt state into visible text, options, highlighting, and key hints.

Data flow: It receives a screen area and a terminal buffer to draw into. It clears the area, builds a vertical column of text lines, inserts action-specific wording, adds explanations for the two directory choices, draws two selectable rows, and adds an Enter-key hint. The result is written into the buffer for the terminal to display.

Call relations: The terminal rendering system calls this whenever run_cwd_selection_prompt draws the screen. It asks CwdPromptAction::verb and CwdPromptAction::past_participle for wording and uses selection_option_row to make the two menu rows look consistent with other selection lists.

Call graph: calls 5 internal fn (past_participle, verb, tlbr, new, selection_option_row); 3 external calls (from, format!, vec!).

fn new_prompt() -> CwdPromptScreen

Purpose: Builds a standard test prompt with fixed example directories. This keeps the tests short and makes their expected output stable.

Data flow: It creates a dummy frame requester and supplies fixed resume/current/session values to CwdPromptScreen::new. It returns the ready-made screen for tests to use.

Call relations: The snapshot and key-behavior tests call this helper whenever they need a normal resume prompt without repeating the setup.

Call graph: calls 2 internal fn (new, test_dummy).

fn cwd_prompt_snapshot()

Purpose: Checks that the default resume prompt still looks the way the project expects. This catches accidental visual changes in the terminal UI.

Data flow: It creates the standard prompt, renders it into a fake 80-by-14 terminal, and compares the captured terminal output with a stored snapshot. The test passes only if the rendered screen matches.

Call relations: It uses tests::new_prompt for setup and then relies on the screen's rendering implementation, CwdPromptScreen::render_ref, through the terminal drawing call.

Call graph: calls 1 internal fn (new); 3 external calls (assert_snapshot!, new, new_prompt).

fn cwd_prompt_fork_snapshot()

Purpose: Checks the visual output for the fork version of the prompt. This makes sure the wording changes correctly from resume to fork.

Data flow: It creates a prompt using CwdPromptAction::Fork, renders it in a fake terminal, and compares the result to a stored snapshot. Any unexpected wording or layout change makes the test fail.

Call relations: It constructs the screen with CwdPromptScreen::new and exercises the same rendering path used by the real prompt, especially the action-specific wording functions.

Call graph: calls 3 internal fn (new, new, test_dummy); 2 external calls (assert_snapshot!, new).

fn cwd_prompt_selects_session_by_default()

Purpose: Verifies that pressing Enter immediately selects the session directory. This protects the default behavior of the prompt.

Data flow: It creates a standard prompt, sends it an Enter key event, then reads back the stored selection. The expected result is Session.

Call relations: It uses tests::new_prompt, drives the screen through CwdPromptScreen::handle_key, and checks the result through CwdPromptScreen::selection.

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

fn cwd_prompt_can_select_current()

Purpose: Verifies that the user can move to the current directory option and select it. This protects the basic keyboard navigation path.

Data flow: It creates a standard prompt, sends a Down key event to move the highlight, then sends Enter to choose the highlighted option. It checks that the final selection is Current.

Call relations: It exercises the same route a real user would take: handle_key moves the highlight through CwdSelection::next, then handle_key selects it, and the test reads the result with selection.

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

fn cwd_prompt_ctrl_c_exits_instead_of_selecting()

Purpose: Verifies that Ctrl-C exits the prompt rather than choosing a directory. This matters because Ctrl-C is commonly understood as cancel.

Data flow: It creates a standard prompt, sends a Ctrl-C key event, then checks two things: no selection was stored, and the screen reports that it is done. The expected result is a cancelled prompt.

Call relations: It drives CwdPromptScreen::handle_key through the cancellation branch and checks the state using selection and is_done, matching what run_cwd_selection_prompt relies on in the real event loop.

Call graph: 5 external calls (Char, new, assert!, assert_eq!, new_prompt).

fn handle_paste(&mut self, _pasted: String)

Purpose: This is the default paste behavior for anything that says it can receive keyboard input. By default, pasted text is ignored unless a specific screen overrides this method.

Data flow: Pasted text goes in, but this default version does nothing with it. Nothing is returned and no state changes.

Call relations: Individual onboarding pieces can choose to provide their own paste behavior. The broader input-routing code can call handle_paste safely without needing to know whether a particular step actually accepts pasted text.

async fn new(tui: &mut Tui, args: OnboardingScreenArgs) -> Self

Purpose: This builds the onboarding screen from the current configuration and startup choices. It decides which steps should appear and prepares each one with the information it needs.

Data flow: It receives the terminal interface, login status, configuration, optional app-server request handle, and flags saying whether login or trust screens should be shown. It creates a welcome step, optionally creates an auth step, optionally resolves the project directory to trust and creates a trust step, then returns a ready-to-use OnboardingScreen.

Call relations: run_onboarding_app calls this at the start of onboarding. During setup it asks the terminal for a frame requester, may ask platform-specific code about Windows sandbox state, and may ask git utilities for the best project root to trust.

Call graph: calls 2 internal fn (new, level_from_config); called by 1 (run_onboarding_app); 11 external calls (new, new, new, resolve_root_git_project_for_trust, frame_requester, Auth, TrustDirectory, Welcome, matches!, new (+1 more)).

fn current_steps_mut(&mut self) -> Vec<&mut Step>

Purpose: This finds the steps that are currently visible and returns them in a form that can be changed. It includes completed visible steps and stops at the first step still in progress.

Data flow: It reads the screen's step list and checks each step's state. Hidden steps are skipped, completed steps are included, and the first in-progress step is included before stopping; the result is a list of mutable step references.

Call relations: Keyboard and paste routing use this when they need to send input to the active step. It is the helper that keeps later, not-yet-reached steps from receiving input too early.

Call graph: called by 2 (handle_key_event, handle_paste); 1 external calls (new).

fn current_steps(&self) -> Vec<&Step>

Purpose: This finds the steps that should be visible without allowing them to be changed. It gives drawing and animation code a safe view of the current onboarding stack.

Data flow: It reads the step list, skips hidden steps, includes completed steps, includes the first in-progress step, and returns shared references to those steps.

Call relations: Rendering uses this to know what to draw. Animation suppression also uses it to inspect only the steps that are currently on screen.

Call graph: called by 2 (render_ref, should_suppress_animations); 1 external calls (new).

fn should_suppress_animations(&self) -> bool

Purpose: This decides whether onboarding animations should be paused. It pauses them when the auth screen is showing copyable login material, so terminal selection is not disrupted by redraws.

Data flow: It looks at the currently visible steps. If an auth step says animations should be suppressed, this returns true; otherwise it returns false.

Call relations: Rendering calls this before drawing. The result is passed into visible widgets so the whole onboarding view can stay still when the user may need to copy text.

Call graph: calls 1 internal fn (current_steps); called by 1 (render_ref).

fn is_auth_in_progress(&self) -> bool

Purpose: This checks whether the sign-in step is currently the unfinished active step. It is used to decide what quitting should mean while login is underway.

Data flow: It scans all steps for the auth step and checks whether that step reports an in-progress state. It returns true if active sign-in is still underway, otherwise false.

Call relations: The key handler calls this when a quit shortcut is pressed. If auth is in progress, quitting cancels login work and marks the whole app for exit rather than leaving the user unauthenticated at another prompt.

Call graph: called by 1 (handle_key_event).

fn is_done(&self) -> bool

Purpose: This tells the main onboarding loop whether it can stop. Onboarding is done either because it was explicitly marked done or because no step is still in progress.

Data flow: It reads the screen's is_done flag and the state of every step. It returns a boolean answer and does not change anything.

Call relations: run_onboarding_app checks this as the condition for its event loop. Once it returns true, onboarding finishes and returns its result.

fn should_exit(&self) -> bool

Purpose: This reports whether finishing onboarding should also exit the whole application. It separates “onboarding is complete” from “the user wants to leave.”

Data flow: It reads the screen's should_exit flag and returns it. No other state changes.

Call relations: After the event loop ends, run_onboarding_app includes this value in the OnboardingResult so the caller can decide whether to continue launching the app or stop.

fn cancel_auth_if_active(&self)

Purpose: This asks the auth widget to cancel any active login attempt. It is used when the user quits while authentication is still underway.

Data flow: It scans the step list for the auth step. If found, it tells that widget to cancel its active attempt; it returns nothing.

Call relations: The key handler calls this during quit handling when sign-in is in progress. This gives the auth widget a chance to stop background login work before onboarding ends.

Call graph: called by 1 (handle_key_event).

fn auth_widget_mut(&mut self) -> Option<&mut AuthModeWidget>

Purpose: This finds the auth widget, if onboarding has one, and returns it in a form that can be updated. It avoids making callers search through every possible step type themselves.

Data flow: It scans the mutable step list. If it finds an auth step, it returns a mutable reference to that auth widget; otherwise it returns nothing.

Call relations: Server-notification handling uses this helper before forwarding account login and account update messages into the auth UI.

Call graph: called by 1 (handle_app_server_notification).

fn handle_app_server_notification(&mut self, notification: ServerNotification)

Purpose: This receives account-related messages from the app server and forwards the relevant ones to the auth screen. Other server messages are ignored here because they do not affect onboarding.

Data flow: A server notification comes in. If it says account login completed or account data updated, the function finds the auth widget and passes the message to it; otherwise it leaves onboarding unchanged.

Call relations: run_onboarding_app calls this when the app-server event stream produces a server notification. It uses auth_widget_mut so only the auth step needs to know the details of login updates.

Call graph: calls 1 internal fn (auth_widget_mut).

fn api_key_entry_context(&self) -> ApiKeyEntryContext

Purpose: This checks whether the auth screen is currently in API-key typing mode and whether the input field already contains text. That small summary is needed to avoid treating a typed q as a quit command at the wrong time.

Data flow: It searches for the auth step and asks it two questions: is API-key entry active, and does the field have text? It returns those two answers in an ApiKeyEntryContext, or a default “not active, no text” context if there is no auth step.

Call relations: The key handler calls this before deciding whether a quit shortcut should really quit. The result is passed to suppress_quit_while_typing_api_key.

Call graph: called by 1 (handle_key_event).

fn handle_key_event(&mut self, key_event: KeyEvent)

Purpose: This is the main keyboard router for onboarding. It decides whether a key press means quit, text input, or a command for the current step.

Data flow: A key event comes in. Non-press events are ignored; real presses are checked against quit rules, including the API-key typing guard. If it is a quit, onboarding is marked done and active auth may be canceled. Otherwise the welcome widget and the current active step receive the key. If the trust step requests quitting, the screen is marked done and set to exit. A new frame is requested at the end.

Call relations: The main event loop calls this whenever the terminal reports a key event. It consults helpers for auth state, API-key context, and visible mutable steps, then schedules a redraw so the user sees the result.

Call graph: calls 6 internal fn (api_key_entry_context, cancel_auth_if_active, current_steps_mut, is_auth_in_progress, suppress_quit_while_typing_api_key, schedule_frame); 1 external calls (matches!).

fn handle_paste(&mut self, pasted: String)

Purpose: This sends pasted text to the currently active onboarding step. Empty pastes are ignored because they cannot change anything.

Data flow: Pasted text comes in. If it is not empty, the function finds the current active step and passes the text to that step, then asks the terminal to draw again.

Call relations: The main event loop calls this for paste events. It uses current_steps_mut to make sure only the active visible step receives the pasted text.

Call graph: calls 2 internal fn (current_steps_mut, schedule_frame).

fn suppress_quit_while_typing_api_key(
    key_event: KeyEvent,
    api_key_entry_context: ApiKeyEntryContext,
) -> bool

Purpose: This decides whether a quit shortcut should be treated as normal typed text instead. It protects users from accidentally exiting while entering an API key.

Data flow: It receives a key event and a short description of API-key entry state. It returns true only when API-key entry is active, the field already has text, the key is a printable character, and the key is not combined with Control or Alt.

Call relations: The onboarding key handler calls this before honoring a quit shortcut. The tests call it directly to prove that plain printable quit keys are suppressed during API-key typing, while empty fields and Control-key exits still work.

Call graph: called by 5 (handle_key_event, does_not_suppress_control_quit_key_during_api_key_entry, does_not_suppress_printable_quit_key_when_api_key_input_is_empty, does_not_suppress_when_not_in_api_key_entry, suppresses_printable_quit_key_during_api_key_entry); 1 external calls (matches!).

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Purpose: This draws the onboarding screen into the terminal buffer. It lays out visible steps from top to bottom and gives each step only the space it needs.

Data flow: It receives a screen area and a drawing buffer. It first decides whether animations should be paused, tells visible widgets about that, clears the area, then renders each visible step into a temporary buffer to measure its used height before drawing it into the real buffer.

Call relations: The terminal draw calls in run_onboarding_app use this to display onboarding. It relies on current_steps to know which steps are visible and on should_suppress_animations to keep copyable login material stable.

Call graph: calls 2 internal fn (current_steps, should_suppress_animations); 2 external calls (empty, new).

fn handle_key_event(&mut self, key_event: KeyEvent)

Purpose: This forwards a key event to whichever concrete widget the step contains. It lets the rest of the onboarding code treat welcome, auth, and trust steps uniformly.

Data flow: A key event and a step go in. The function matches the step's kind and passes the key to the matching widget; it returns nothing.

Call relations: The onboarding screen calls this after it has decided which step should receive input. This small adapter keeps the top-level router from duplicating widget-specific calls everywhere.

fn handle_paste(&mut self, pasted: String)

Purpose: This forwards pasted text to steps that can use it. Welcome ignores paste, while auth and trust can receive pasted content.

Data flow: Pasted text and a step go in. If the step is auth or trust, the text is passed to that widget; if it is welcome, nothing changes.

Call relations: The onboarding screen's paste handler calls this for the active step. It hides the difference between step types behind one common method.

fn get_step_state(&self) -> StepState

Purpose: This asks the concrete widget inside a step whether it is hidden, in progress, or complete. The top-level flow uses that answer to decide what should be visible and active.

Data flow: A step goes in. The function calls the matching widget's state method and returns the resulting StepState.

Call relations: Helpers such as current_steps, current_steps_mut, and is_done depend on this shared view of step state. It is the bridge between individual widgets and the overall onboarding sequence.

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Purpose: This draws whichever widget is stored in a step. It gives the rendering system one common way to draw welcome, auth, or trust content.

Data flow: It receives a drawing area and buffer. It matches the step's kind and asks the contained widget to render itself into that area.

Call relations: OnboardingScreen::render_ref calls this while measuring and drawing each visible step. This keeps the screen renderer independent of each widget's internal drawing details.

async fn run_onboarding_app(
    args: OnboardingScreenArgs,
    mut app_server: Option<&mut AppServerSession>,
    tui: &mut Tui,
) -> Result<OnboardingResult>

Purpose: This is the live onboarding loop. It builds the screen, draws it, listens for terminal input and app-server messages, and returns what happened.

Data flow: It receives onboarding arguments, an optional app-server session, and the terminal interface. It creates an OnboardingScreen, draws it, then loops until onboarding is done. During the loop it routes key, paste, draw, resize, and server events; it may persist project trust; when finished it returns whether trust was saved and whether the app should exit.

Call relations: The larger terminal app calls this during startup. Inside the loop it hands keyboard and paste events to the onboarding screen, forwards login notifications from the app server, performs redraws, and calls persist_selected_trust once the user chooses to trust a directory.

Call graph: calls 1 internal fn (new); called by 1 (run_ratatui_app); 4 external calls (draw, event_stream, pin!, select!).

async fn persist_selected_trust(
    onboarding_screen: &mut OnboardingScreen,
    request_handle: Option<AppServerRequestHandle>,
) -> bool

Purpose: This saves the user's choice to trust the current project directory. If saving fails, it keeps the trust step open and shows an error instead of pretending the choice worked.

Data flow: It receives the onboarding screen and an optional app-server request handle. It searches for a trust step whose selection is “trust,” then tries to write that trusted project through the app server. On success it returns true. On failure it formats the error, logs it, clears the selection, stores an error message in the trust widget, and returns false.

Call relations: run_onboarding_app calls this after key events until trust has been persisted. A test also calls it directly to confirm that failure leaves the trust step in progress for the user to retry or choose differently.

Call graph: calls 2 internal fn (format_config_error, write_trusted_project); called by 1 (trust_persistence_failure_keeps_trust_step_in_progress); 3 external calls (eyre!, format!, error!).

fn suppresses_printable_quit_key_during_api_key_entry()

Purpose: This test proves that a plain printable quit key is ignored as a quit command once the user has started typing an API key.

Data flow: It builds a q key event with no modifiers and an API-key context saying entry is active and has text. It calls the suppression helper and checks that the answer is true.

Call relations: The test runner calls this as part of the file's safety checks. It directly exercises suppress_quit_while_typing_api_key, the helper used by the real key handler.

Call graph: calls 1 internal fn (suppress_quit_while_typing_api_key); 3 external calls (Char, new, assert!).

fn does_not_suppress_printable_quit_key_when_api_key_input_is_empty()

Purpose: This test proves that plain q can still quit when the API-key input field is empty. That keeps the quit shortcut convenient before typing begins.

Data flow: It creates a plain q key event and an API-key context where entry is active but has no text. It calls the helper and checks that suppression is false.

Call relations: The test runner calls this to guard the intended empty-field behavior. It checks the same helper used by onboarding's key-routing code.

Call graph: calls 1 internal fn (suppress_quit_while_typing_api_key); 3 external calls (Char, new, assert!).

fn does_not_suppress_control_quit_key_during_api_key_entry()

Purpose: This test proves that Control-key quit shortcuts still work while typing an API key. These shortcuts are treated as explicit exits, not normal text.

Data flow: It creates a Control-modified character key event and an API-key context where entry is active and has text. It calls the helper and checks that suppression is false.

Call relations: The test runner calls this to make sure the emergency-exit behavior stays available. It directly verifies the rule that Control or Alt modifiers bypass printable-key suppression.

Call graph: calls 1 internal fn (suppress_quit_while_typing_api_key); 3 external calls (Char, new, assert!).

fn does_not_suppress_when_not_in_api_key_entry()

Purpose: This test proves that the quit-key suppression only applies during API-key entry. Outside that mode, normal quit handling should not be blocked.

Data flow: It creates a plain character key event and a context saying API-key entry is not active. It calls the helper and checks that suppression is false.

Call relations: The test runner calls this to keep the API-key guard narrowly scoped. It protects the rest of onboarding from accidentally losing quit shortcuts.

Call graph: calls 1 internal fn (suppress_quit_while_typing_api_key); 3 external calls (Char, new, assert!).

async fn trust_persistence_failure_keeps_trust_step_in_progress()

Purpose: This test proves that failing to save a trusted project does not silently finish the trust step. The user should see an error and remain able to act.

Data flow: It builds a minimal onboarding screen with a trust step already selected, but passes no app-server request handle. It calls persist_selected_trust, checks that it returns false, then verifies the selection was cleared, the step is still in progress, and the error mentions the unavailable app server.

Call relations: The test runner calls this to cover the failure path of persist_selected_trust. It makes sure the main onboarding loop will not move on after a trust-save failure.

Call graph: calls 2 internal fn (persist_selected_trust, test_dummy); 4 external calls (assert!, assert_eq!, panic!, vec!).

fn handle_key_event(&mut self, key_event: KeyEvent)

Purpose: This reacts to keyboard input while the welcome screen is active. If animations are enabled and the user presses the animation-toggle shortcut, it switches the welcome background to another random ASCII animation variant.

Data flow: It receives one key event from the terminal. It first ignores the event if animations are disabled. Otherwise, it checks that the key was a press, not a release or repeat-like event, and that it matches the configured animation shortcut. If it matches, it asks the animation object to pick a new variant; the visible result is that future draws can show different ASCII art.

Call relations: The onboarding screen calls this when keyboard input arrives for the welcome step. Inside, it hands the actual variant change to the animation object through pick_random_variant, and writes a warning log message for visibility while debugging.

Call graph: calls 1 internal fn (pick_random_variant); 1 external calls (warn!).

fn new(
        is_logged_in: bool,
        request_frame: FrameRequester,
        animations_enabled: bool,
    ) -> Self

Purpose: This builds a fresh welcome widget with the right login state, animation setup, and animation policy. Code uses it when creating the onboarding welcome screen.

Data flow: It receives whether the user is logged in, a frame requester used by the animation to ask the terminal to redraw, and a flag saying whether animations are enabled. It creates a new AsciiAnimation, stores the flags, starts with animations not suppressed, and starts without a saved layout area. The result is a ready-to-render WelcomeWidget.

Call relations: Higher-level onboarding setup calls this when it needs the welcome panel. The tests also call it to create normal widgets before drawing them. It delegates animation construction to AsciiAnimation::new, passing along the frame requester so the animation can keep the screen refreshed.

Call graph: calls 1 internal fn (new); called by 3 (new, welcome_renders_animation_on_first_draw, welcome_skips_animation_below_height_breakpoint); 1 external calls (new).

fn update_layout_area(&self, area: Rect)

Purpose: This records the screen area that should be used when deciding whether the animation has enough room. It lets layout code tell the widget about the real space available to it.

Data flow: It receives a rectangle describing part of the terminal screen. It stores that rectangle inside the widget. Later, rendering reads this saved value to decide whether the ASCII animation should be shown or skipped.

Call relations: Layout code calls this before rendering when it has calculated the welcome screen’s actual area. render_ref later uses the stored area, falling back to the render area if no separate layout area has been provided.

fn set_animations_suppressed(&self, suppressed: bool)

Purpose: This temporarily turns welcome animations off or back on without changing the global animation setting. It is useful when another screen state needs the welcome page to stop moving for a while.

Data flow: It receives a boolean value: true means suppress animations, false means allow them again. It stores that value in the widget. Later rendering and keyboard behavior use this stored state to avoid scheduling or showing animation frames while suppressed.

Call relations: Other onboarding UI code can call this when animations should pause, for example if another overlay or mode should keep the screen still. render_ref reads the stored value before scheduling or drawing animation frames.

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Purpose: This draws the welcome widget into the terminal buffer. It clears the area, optionally draws the ASCII animation, and always draws the welcome message.

Data flow: It receives a rectangle saying where to draw and a mutable terminal buffer where characters are placed. It clears that rectangle, schedules the next animation frame if animations are active, checks whether the available layout is large enough, then builds a list of text lines. If there is enough room, it adds the current ASCII animation frame first. Finally, it adds the welcome text and renders all lines as a paragraph into the buffer.

Call relations: The terminal UI rendering system calls this whenever the welcome widget needs to be painted. It asks the AsciiAnimation for the current frame and to schedule future redraws, then hands the finished lines to Ratatui’s Paragraph, which is the library component that writes formatted text into the terminal buffer.

Call graph: calls 2 internal fn (current_frame, schedule_next_frame); 4 external calls (from, new, new, vec!).

fn get_step_state(&self) -> StepState

Purpose: This tells the onboarding flow whether the welcome step should be visible and considered done. It hides the welcome step for users who are already logged in.

Data flow: It reads the widget’s is_logged_in flag. If the flag is true, it returns StepState::Hidden. If the flag is false, it returns StepState::Complete. It does not change any stored data.

Call relations: The onboarding screen asks this through the StepStateProvider trait when deciding which steps to show and how to advance through them. This function supplies the welcome screen’s simple rule: logged-in users do not need to see it, and logged-out users can pass through it.

fn row_containing(buf: &Buffer, needle: &str) -> Option<u16>

Purpose: This test helper finds which row of a terminal buffer contains a given piece of text. The tests use it to check where the welcome message appears on screen.

Data flow: It receives a rendered buffer and a text snippet to search for. It scans each row from top to bottom, joins the visible symbols in that row into a string, and checks whether the row contains the snippet. It returns the row number if found, or nothing if the text is absent.

Call relations: The rendering tests call this after drawing the widget into a fake buffer. It turns the buffer’s grid of terminal cells into an easy answer: where did the word “Welcome” land?

fn welcome_renders_animation_on_first_draw()

Purpose: This test proves that the welcome screen includes the animation when the terminal is large enough. It protects against accidentally removing or delaying the first animation frame.

Data flow: It creates a welcome widget with animations enabled, prepares a buffer exactly large enough for the animation threshold, counts the current animation frame’s lines, and renders the widget. It then searches for the welcome text and checks that it appears after the animation plus one blank line.

Call relations: The test uses WelcomeWidget::new to build a normal widget, renders it through the widget interface, and uses tests::row_containing to inspect the result. It confirms the main drawing path in WelcomeWidget::render_ref when animation display is allowed.

Call graph: calls 2 internal fn (new, test_dummy); 4 external calls (empty, new, assert_eq!, row_containing).

fn welcome_skips_animation_below_height_breakpoint()

Purpose: This test proves that the welcome screen skips the ASCII animation when the terminal is too short. That keeps the interface readable instead of showing clipped art.

Data flow: It creates a welcome widget with animations enabled, but gives it a buffer one row shorter than the required animation height. After rendering, it searches for the welcome text and expects it to be on the first row, showing that no animation lines were drawn above it.

Call relations: The test builds the widget with WelcomeWidget::new, draws it, then asks tests::row_containing where the welcome message appeared. It checks the small-screen branch of WelcomeWidget::render_ref.

Call graph: calls 2 internal fn (new, test_dummy); 4 external calls (empty, new, assert_eq!, row_containing).

fn ctrl_dot_changes_animation_variant()

Purpose: This test checks that pressing Control plus period changes the welcome animation variant. It ensures the documented shortcut works in terminals that report that key combination in this form.

Data flow: It creates a widget with two known animation variants and starts on the first one. It records the current frame, sends a Control-period key event to the widget, then reads the frame again. The test passes only if the frame changed.

Call relations: The test calls WelcomeWidget::handle_key_event directly with a fake key event. That exercises the shortcut path, which then calls the animation’s variant-picking logic.

Call graph: calls 2 internal fn (with_variants, test_dummy); 4 external calls (new, Char, new, assert_ne!).

fn ctrl_shift_dot_changes_animation_variant()

Purpose: This test checks that Control plus Shift plus period also changes the welcome animation variant. This matters because different terminals may report the same practical shortcut with slightly different modifier keys.

Data flow: It creates a widget with two known animation variants and starts on the first one. It saves the current frame, sends a Control-Shift-period key event, and then reads the current frame again. The expected result is that the frame is different after the key press.

Call relations: Like the Control-period test, this calls WelcomeWidget::handle_key_event directly. It verifies the compatibility version of the animation shortcut, making sure the key binding list accepts this terminal-specific variation.

Call graph: calls 2 internal fn (with_variants, test_dummy); 4 external calls (new, Char, new, assert_ne!).

fn mark_url_hyperlink(buf: &mut Buffer, area: Rect, url: &str)

Purpose: Marks the rendered characters of a visible URL so terminals treat the whole URL as one clickable link. This is useful when a long login URL wraps across multiple terminal rows.

Data flow: It receives a terminal buffer, the rectangle to scan, and the URL text. It passes those to the shared terminal hyperlink helper, which wraps the matching styled cells with terminal hyperlink escape codes. The buffer is changed in place; nothing is returned.

Call relations: The browser-login screen calls this after drawing the auth URL. Tests also call it directly to prove wrapped URLs and unsafe control characters are handled correctly.

Call graph: calls 1 internal fn (mark_url_hyperlink); called by 3 (render_continue_in_browser, mark_url_hyperlink_sanitizes_control_chars, mark_url_hyperlink_wraps_cyan_underlined_cells).

fn mark_underlined_hyperlink(buf: &mut Buffer, area: Rect, url: &str)

Purpose: Marks underlined text in a terminal buffer as a clickable terminal hyperlink. It is a small local wrapper around the shared hyperlink helper.

Data flow: It receives a buffer, an area, and a URL. It forwards them to the shared helper, which edits matching underlined cells in the buffer. It returns no value.

Call relations: This file exposes the helper for auth-related rendering, although the listed call graph does not show another function in this file using it directly.

Call graph: calls 1 internal fn (mark_underlined_hyperlink).

fn onboarding_request_id() -> codex_app_server_protocol::RequestId

Purpose: Creates a fresh request ID for messages sent from onboarding to the app server. A request ID is a unique label that lets the server and client tell one request from another.

Data flow: It generates a new UUID, which is a random unique identifier, turns it into text, and wraps it in the protocol’s request ID type. The result is used in outgoing app-server requests.

Call relations: API-key saving, ChatGPT login start, and login cancellation all call this before sending a request so each request can be tracked separately.

Call graph: called by 3 (save_api_key, start_chatgpt_login, cancel_login_attempt); 2 external calls (new_v4, String).

async fn cancel_login_attempt(
    request_handle: &AppServerRequestHandle,
    login_id: String,
)

Purpose: Asks the app server to cancel a login that was already started. This prevents abandoned browser or device-code login attempts from staying active after the user backs out.

Data flow: It receives an app-server request handle and a login ID. It builds a cancel request with a fresh request ID and sends it asynchronously. It ignores the response because cancellation is best-effort.

Call relations: When the user presses cancel during an active ChatGPT or device-code login, AuthModeWidget::cancel_active_attempt starts this function in the background.

Call graph: calls 1 internal fn (onboarding_request_id); called by 1 (cancel_active_attempt).

fn pending(request_id: String) -> Self

Purpose: Creates the starting state for a device-code login before the server has returned the code and verification URL. It records that a request is underway.

Data flow: It receives a request ID and builds a state object with no login ID, no verification URL, and no user code yet. The returned state means “waiting for device-code details.”

Call relations: The headless ChatGPT login helper uses this while requesting a code. Tests use it to check that the auth widget suppresses animations even while the code is still being fetched.

Call graph: called by 4 (start_headless_chatgpt_login, device_code_attempt_matches_only_for_matching_request_id, pending_device_code_state, auth_widget_suppresses_animations_while_requesting_device_code).

fn ready(
        request_id: String,
        login_id: String,
        verification_url: String,
        user_code: String,
    ) -> Self

Purpose: Creates the device-code state once the server has provided everything the user needs. This is the state where the screen can show a URL and one-time code.

Data flow: It receives the request ID, login ID, verification URL, and user code. It stores them in a state object and returns it for rendering and later completion matching.

Call relations: The headless login helper uses this after receiving device-code details. Tests also build this state to check cancellation, animation suppression, and successful login completion.

Call graph: called by 4 (start_headless_chatgpt_login, auth_widget_suppresses_animations_when_device_code_is_visible, cancel_active_attempt_notifies_device_code_login, device_code_login_completion_advances_to_success_message).

fn login_id(&self) -> Option<&str>

Purpose: Returns the login ID for a device-code attempt, if the server has assigned one. The login ID is used to match later success or failure notifications to the correct attempt.

Data flow: It reads the optional stored login ID and returns it as borrowed text when present. It does not change the state.

Call relations: Other auth logic uses this when deciding whether a cancel request or login-completed notification belongs to the current device-code login.

fn is_showing_copyable_auth(&self) -> bool

Purpose: Checks whether the device-code screen has both pieces of information the user can copy: the verification URL and the one-time code.

Data flow: It reads the stored URL and code, checks that both exist and are not empty, and returns true only in that case. It does not change anything.

Call relations: The device-code renderer uses this to decide whether to show copy-friendly login information or a still-loading view.

Call graph: called by 1 (render_device_code_login).

fn handle_key_event(&mut self, key_event: KeyEvent)

Purpose: Responds to keyboard input on the auth screen. It moves the selection, starts the chosen sign-in method, advances past a success message, or cancels an active login.

Data flow: It receives a key event. First it gives API-key entry a chance to consume the key; if not, it checks navigation, number shortcuts, confirm, and cancel. The result may be a changed highlighted option, changed sign-in state, an app-server request, or a scheduled redraw.

Call relations: The onboarding screen calls this when the user presses a key. It delegates to option selection, API-key editing, login start, and cancellation helpers depending on the current state.

Call graph: calls 5 internal fn (cancel_active_attempt, handle_api_key_entry_key_event, handle_sign_in_option, move_highlight, select_option_by_index); 1 external calls (info!).

fn handle_paste(&mut self, pasted: String)

Purpose: Responds to pasted text, mainly so users can paste an API key into the API-key input box.

Data flow: It receives pasted text and passes it to the API-key paste handler. If the auth screen is not currently accepting an API key, the paste has no effect.

Call relations: The onboarding screen calls this when terminal paste input arrives. It hands off to handle_api_key_entry_paste for the actual state update.

Call graph: calls 1 internal fn (handle_api_key_entry_paste).

fn set_animations_suppressed(&self, suppressed: bool)

Purpose: Records whether animations should be temporarily hidden for this widget. This lets surrounding UI avoid distracting motion during sensitive or copy-focused login screens.

Data flow: It receives a boolean value and stores it in an internal cell. It returns nothing and does not redraw by itself.

Call relations: Other UI code can call this to tell the auth widget whether animation should be suppressed. Rendering later reads this flag when deciding whether to shimmer text.

fn should_suppress_animations(&self) -> bool

Purpose: Reports whether the current auth state is one where animations should be avoided. Browser and device-code login screens are treated as copy-sensitive or focus-sensitive.

Data flow: It reads the shared sign-in state and returns true if the user is in browser-login or device-code-login mode. Otherwise it returns false.

Call relations: Tests exercise this behavior for device-code states. The surrounding onboarding UI can use it to decide whether to reduce motion.

Call graph: 1 external calls (matches!).

fn cancel_active_attempt(&self)

Purpose: Cancels the current ChatGPT login attempt, if one is active, and returns the screen to the method picker. This gives the user a clean way out of browser or device-code login.

Data flow: It reads the current sign-in state. If there is an active browser or device-code login with a login ID, it starts a background cancellation request to the app server. It then clears the error, switches back to pick mode, and asks the UI to redraw.

Call relations: handle_key_event calls this when the cancel key is pressed. It uses cancel_login_attempt for the server notification and set_error to clear visible errors.

Call graph: calls 3 internal fn (set_error, cancel_login_attempt, schedule_frame); called by 1 (handle_key_event); 2 external calls (clone, spawn).

fn set_error(&self, message: Option<String>)

Purpose: Stores the error message that should be shown on the auth screen. Passing no message clears the error.

Data flow: It receives an optional string and writes it into the shared error slot. The next render can read and display that value.

Call relations: Many flows call this before or after state changes: API-key editing, login start, login completion, cancellation, and disabled-login handling.

Call graph: called by 9 (cancel_active_attempt, disallow_api_login, handle_api_key_entry_key_event, handle_api_key_entry_paste, on_account_login_completed, save_api_key, start_api_key_entry, start_chatgpt_login, start_device_code_login).

fn error_message(&self) -> Option<String>

Purpose: Returns the current auth error message, if there is one. Renderers use it to show helpful feedback to the user.

Data flow: It reads the shared error slot, clones the optional string, and returns it. It does not change state.

Call relations: The pick-mode and API-key-entry renderers call this when deciding whether to draw an error line.

Call graph: called by 2 (render_api_key_entry, render_pick_mode).

fn is_api_key_entry_active(&self) -> bool

Purpose: Tells other code whether the auth screen is currently showing the API-key input field.

Data flow: It reads the sign-in state and returns true only when that state is API-key entry. It returns false if the state cannot be read or is anything else.

Call relations: This is a status helper for surrounding UI code that may need to know whether typed text should be treated as API-key input.

fn api_key_entry_has_text(&self) -> bool

Purpose: Tells other code whether the API-key field currently contains any text. This can be used to decide whether leaving the field would discard typed input.

Data flow: It reads the sign-in state. If the state is API-key entry, it checks whether the stored value is empty and returns the answer.

Call relations: This is a small query helper for the larger onboarding screen or input system.

fn confirm_binding(&self) -> KeyBinding

Purpose: Returns the key binding shown as the confirm action on this screen. It keeps rendered instructions aligned with the actual key handling.

Data flow: It reads the first configured confirm key binding and returns it. No state is changed.

Call relations: Render functions use this when drawing text like “Press Enter to continue” or “Press Enter to save.”

fn cancel_binding(&self) -> KeyBinding

Purpose: Returns the key binding shown as the cancel action on this screen. It keeps the on-screen help text consistent with input behavior.

Data flow: It reads the first configured cancel key binding and returns it. No state is changed.

Call relations: Browser-login and API-key-entry renderers use this when showing cancel instructions.

fn is_api_login_allowed(&self) -> bool

Purpose: Checks whether API-key login is allowed under the current workspace rules. Some workspaces may force ChatGPT login only.

Data flow: It reads the optional forced login method. It returns false when the forced method is ChatGPT, and true otherwise.

Call relations: Option display, selection handling, API-key start, and API-key saving all call this so the UI cannot bypass the forced-login rule.

Call graph: called by 6 (displayed_sign_in_options, handle_sign_in_option, render_pick_mode, save_api_key, selectable_sign_in_options, start_api_key_entry); 1 external calls (matches!).

fn is_chatgpt_login_allowed(&self) -> bool

Purpose: Checks whether ChatGPT login is allowed under the current workspace rules. Some workspaces may force API-key login only.

Data flow: It reads the optional forced login method. It returns false when the forced method is API, and true otherwise.

Call relations: The picker, navigation list, and sign-in option handler use this to hide or block ChatGPT-based choices when needed.

Call graph: called by 4 (displayed_sign_in_options, handle_sign_in_option, render_pick_mode, selectable_sign_in_options); 1 external calls (matches!).

fn displayed_sign_in_options(&self) -> Vec<SignInOption>

Purpose: Builds the list of sign-in options that should be shown to the user. This list can include disabled-looking information differently from what is selectable.

Data flow: It starts with ChatGPT as a displayed option, adds device-code if ChatGPT login is allowed, and adds API key if API login is allowed. It returns the resulting list.

Call relations: The picker renderer uses this list to draw choices. Number-key selection also uses it to map “first,” “second,” or “third” to a visible option.

Call graph: calls 2 internal fn (is_api_login_allowed, is_chatgpt_login_allowed); called by 2 (render_pick_mode, select_option_by_index); 1 external calls (vec!).

fn selectable_sign_in_options(&self) -> Vec<SignInOption>

Purpose: Builds the list of options the highlight can actually move through. This avoids landing the cursor on choices that are not allowed.

Data flow: It checks the forced-login rules and adds only allowed options to a new list. It returns that list for navigation.

Call relations: move_highlight calls this whenever the user presses up or down.

Call graph: calls 2 internal fn (is_api_login_allowed, is_chatgpt_login_allowed); called by 1 (move_highlight); 1 external calls (new).

fn move_highlight(&mut self, delta: isize)

Purpose: Moves the highlighted sign-in option up or down, wrapping around at the ends. This is the menu-navigation behavior for the picker.

Data flow: It receives a positive or negative movement amount. It finds the current option in the selectable list, calculates the next index with wraparound, and updates highlighted_mode.

Call relations: handle_key_event calls this for the move-up and move-down keys. It relies on selectable_sign_in_options to respect login restrictions.

Call graph: calls 1 internal fn (selectable_sign_in_options); called by 1 (handle_key_event).

fn select_option_by_index(&mut self, index: usize)

Purpose: Chooses a sign-in option by its displayed number. This powers keyboard shortcuts like pressing 1, 2, or 3.

Data flow: It receives a zero-based index, looks up that option in the displayed list, and if one exists passes it to the sign-in option handler. Invalid indexes do nothing.

Call relations: handle_key_event calls this for number shortcuts. It then hands off to handle_sign_in_option to start or reject the chosen flow.

Call graph: calls 2 internal fn (displayed_sign_in_options, handle_sign_in_option); called by 1 (handle_key_event).

fn handle_sign_in_option(&mut self, option: SignInOption)

Purpose: Starts the flow for the selected sign-in method, while enforcing which methods are allowed. It is the main branch point after the user chooses a login type.

Data flow: It receives a sign-in option. For ChatGPT it may start browser login, for device code it may start headless login, and for API key it may open the API-key input or show a disabled message. It updates state through the called helpers.

Call relations: This is called when the user presses confirm on the highlighted option or selects an option by number. It delegates to the specific start functions.

Call graph: calls 6 internal fn (disallow_api_login, is_api_login_allowed, is_chatgpt_login_allowed, start_api_key_entry, start_chatgpt_login, start_device_code_login); called by 2 (handle_key_event, select_option_by_index).

fn disallow_api_login(&mut self)

Purpose: Shows the user that API-key login is not permitted and returns them to the normal picker. This prevents a forced-ChatGPT workspace from accepting an API key.

Data flow: It changes the highlighted option back to ChatGPT, stores a clear error message, sets the state to pick mode, and schedules a redraw.

Call relations: API-key selection, API-key entry start, and API-key saving call this whenever the forced-login rules block API login.

Call graph: calls 2 internal fn (set_error, schedule_frame); called by 3 (handle_sign_in_option, save_api_key, start_api_key_entry).

fn render_pick_mode(&self, area: Rect, buf: &mut Buffer)

Purpose: Draws the sign-in method picker. It explains the choices, highlights the current one, shows disabled-login information, and displays any error.

Data flow: It reads allowed methods, the highlighted method, key bindings, and current error. It builds styled text lines and writes them into the terminal buffer.

Call relations: render_ref calls this whenever the sign-in state is pick mode. It uses option-list and permission helpers so the screen matches the actual rules.

Call graph: calls 4 internal fn (displayed_sign_in_options, error_message, is_api_login_allowed, is_chatgpt_login_allowed); called by 1 (render_ref); 3 external calls (from, new, vec!).

fn render_continue_in_browser(&self, area: Rect, buf: &mut Buffer)

Purpose: Draws the screen shown after browser-based ChatGPT login has started. It tells the user to finish in the browser and shows a fallback URL if available.

Data flow: It reads the current browser-login state and animation settings. It writes status text, the auth URL, remote-machine advice, and cancel instructions into the buffer. If a URL was drawn, it marks it as a terminal hyperlink.

Call relations: render_ref calls this for browser-login state. It uses shimmer_text for optional animation and mark_url_hyperlink so the login URL remains clickable even when wrapped.

Call graph: calls 3 internal fn (shimmer_text, mark_url_hyperlink, schedule_frame_in); called by 1 (render_ref); 4 external calls (from, new, from_millis, vec!).

fn render_chatgpt_success_message(&self, area: Rect, buf: &mut Buffer)

Purpose: Draws the longer success-and-safety message after ChatGPT login completes. It gives the user a brief pause to read important guidance before continuing.

Data flow: It builds lines that confirm sign-in, mention autonomy and review reminders, link to docs and settings, and show the confirm key. It writes those lines to the terminal buffer.

Call relations: render_ref calls this for the intermediate ChatGPT success-message state. Pressing confirm later moves the state to final success.

Call graph: called by 1 (render_ref); 2 external calls (new, vec!).

fn render_chatgpt_success(&self, area: Rect, buf: &mut Buffer)

Purpose: Draws the compact final ChatGPT success line. This is used once the auth step is considered complete.

Data flow: It creates a green confirmation line and writes it to the terminal buffer. It reads no extra data and changes no state.

Call relations: render_ref calls this when the sign-in state is final ChatGPT success.

Call graph: called by 1 (render_ref); 2 external calls (new, vec!).

fn render_api_key_configured(&self, area: Rect, buf: &mut Buffer)

Purpose: Draws the success screen for API-key setup. It confirms that Codex will use usage-based billing with the provided key.

Data flow: It creates a small set of confirmation lines and writes them into the terminal buffer. It changes no state.

Call relations: render_ref calls this after the app server accepts the API key.

Call graph: called by 1 (render_ref); 2 external calls (new, vec!).

fn render_api_key_entry(&self, area: Rect, buf: &mut Buffer, state: &ApiKeyInputState)

Purpose: Draws the API-key entry form. It includes instructions, a bordered input box, save/back key hints, and any validation or save error.

Data flow: It receives the current API-key input state, including the typed value and whether it came from the environment. It splits the screen into intro, input, and footer areas, then writes the appropriate text into each.

Call relations: render_ref calls this while the sign-in state is API-key entry. It reads error_message to show problems like an empty key or save failure.

Call graph: calls 1 internal fn (error_message); called by 1 (render_ref); 8 external calls (default, Length, Min, vertical, from, new, default, vec!).

fn handle_api_key_entry_key_event(&mut self, key_event: &KeyEvent) -> bool

Purpose: Processes keystrokes while the API-key input box is active. It supports cancel, save, backspace, and normal character typing.

Data flow: It receives a key event and checks whether the current state is API-key entry. It may edit the stored key text, clear the environment-prefill marker, set an error, return to pick mode, or trigger saving a trimmed non-empty key. It returns true when it handled the key.

Call relations: handle_key_event gives this function first chance at every key. If it saves, it calls save_api_key; otherwise it schedules redraws after local edits.

Call graph: calls 3 internal fn (save_api_key, set_error, schedule_frame); called by 1 (handle_key_event).

fn handle_api_key_entry_paste(&mut self, pasted: String) -> bool

Purpose: Adds pasted text to the API-key field when that field is active. This makes pasting long keys practical.

Data flow: It receives pasted text, trims surrounding whitespace, and ignores it if empty. If API-key entry is active, it replaces an environment-prefilled value or appends to existing typed text, clears errors, schedules a redraw, and returns true.

Call relations: handle_paste calls this for paste events from the onboarding screen.

Call graph: calls 2 internal fn (set_error, schedule_frame); called by 1 (handle_paste).

fn start_api_key_entry(&mut self)

Purpose: Switches the auth screen into API-key entry mode. If an OPENAI_API_KEY environment variable is available, it pre-fills the field so the user can save or replace it.

Data flow: It first checks whether API login is allowed. If allowed, it clears errors, reads a possible API key from the environment, updates or creates the API-key entry state, and schedules a redraw.

Call relations: handle_sign_in_option calls this when the user chooses API-key login. It uses disallow_api_login if workspace rules forbid the path.

Call graph: calls 4 internal fn (disallow_api_login, is_api_login_allowed, set_error, schedule_frame); called by 1 (handle_sign_in_option); 2 external calls (read_openai_api_key_from_env, ApiKeyEntry).

fn save_api_key(&mut self, api_key: String)

Purpose: Sends the entered API key to the app server so it can be stored and used for future requests. It also updates the UI based on whether saving worked.

Data flow: It receives the API key text, checks that API login is allowed, clears errors, and starts a background app-server request. On success it marks API key configured; on unexpected response or error it restores the entry screen with the key still present and shows an error. It schedules redraws before and after the async work.

Call relations: handle_api_key_entry_key_event calls this after the user confirms a non-empty key. It uses onboarding_request_id for the server request and disallow_api_login if rules changed.

Call graph: calls 5 internal fn (disallow_api_login, is_api_login_allowed, set_error, onboarding_request_id, schedule_frame); called by 1 (handle_api_key_entry_key_event); 5 external calls (clone, format!, spawn, ApiKeyEntry, clone).

fn handle_existing_chatgpt_login(&mut self) -> bool

Purpose: Detects when the user is already signed in with a ChatGPT-compatible account. In that case, it skips starting a new login attempt.

Data flow: It reads login_status. If the status says there is already a ChatGPT account, it sets the state to ChatGPT success, schedules a redraw, and returns true. Otherwise it returns false.

Call relations: Both browser login and device-code login call this before starting. Tests verify that different ChatGPT credential types count as already signed in.

Call graph: calls 1 internal fn (schedule_frame); called by 2 (start_chatgpt_login, start_device_code_login); 1 external calls (matches!).

fn start_chatgpt_login(&mut self)

Purpose: Starts the normal ChatGPT browser sign-in flow. It asks the app server for a login URL, optionally opens the browser, and moves the UI into “continue in browser” mode.

Data flow: It first checks for an existing ChatGPT login. If none exists, it clears errors and sends a background login request to the app server. A successful ChatGPT response stores the login ID and auth URL; errors return the screen to pick mode with an error message.

Call relations: handle_sign_in_option calls this for ChatGPT login. It uses maybe_open_auth_url_in_browser after receiving the URL and onboarding_request_id for the request.

Call graph: calls 4 internal fn (handle_existing_chatgpt_login, set_error, maybe_open_auth_url_in_browser, onboarding_request_id); called by 1 (handle_sign_in_option); 5 external calls (clone, format!, spawn, ChatGptContinueInBrowser, clone).

fn start_device_code_login(&mut self)

Purpose: Starts the device-code version of ChatGPT login, intended for remote or headless machines where opening a browser is inconvenient.

Data flow: It first checks for an existing ChatGPT login. If none exists, it clears errors and hands the widget to the headless-login helper, which begins the device-code request and state updates.

Call relations: handle_sign_in_option calls this when the user chooses device-code login. The detailed flow is delegated to headless_chatgpt_login::start_headless_chatgpt_login.

Call graph: calls 3 internal fn (handle_existing_chatgpt_login, set_error, start_headless_chatgpt_login); called by 1 (handle_sign_in_option).

fn on_account_login_completed(
        &mut self,
        notification: AccountLoginCompletedNotification,
    )

Purpose: Responds to an app-server notification that a ChatGPT login attempt finished. It only acts if the notification belongs to the login currently shown on this screen.

Data flow: It receives a completion notification, extracts the login ID, and compares it with the active browser or device-code login. If it matches, success moves to the ChatGPT success message; failure returns to pick mode and shows the server-provided error. It then schedules a redraw.

Call relations: The broader app event system calls this when login completion notifications arrive. It protects against stale or unrelated login notifications by matching the login ID.

Call graph: calls 2 internal fn (set_error, schedule_frame); 1 external calls (matches!).

fn on_account_updated(&mut self, notification: AccountUpdatedNotification)

Purpose: Updates the widget’s remembered account status after the app server reports an account change.

Data flow: It receives an account-updated notification. If it contains an auth mode, it stores that as the current login status; otherwise it marks the user as not authenticated.

Call relations: The broader app event system calls this when account state changes, so later choices like “already signed in” use fresh information.

fn get_step_state(&self) -> StepState

Purpose: Tells the onboarding screen whether the auth step is still in progress or complete. The enclosing onboarding flow uses this to decide when it can move on.

Data flow: It reads the current sign-in state. Picker, entry, active login, and intermediate success-message states return in-progress; final ChatGPT success and API-key configured return complete.

Call relations: The onboarding screen calls this through the StepStateProvider trait. This file deliberately reports status but does not itself decide full onboarding completion.

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Purpose: Chooses which auth screen to draw based on the current sign-in state. It is the central rendering switch for the widget.

Data flow: It reads the shared sign-in state and dispatches to the matching render function: picker, browser login, device-code login, success message, final success, API-key entry, or API-key configured. The chosen renderer writes into the terminal buffer.

Call relations: The terminal UI framework calls this when drawing the widget. It hands device-code rendering to the headless-login helper and uses local renderers for the other states.

Call graph: calls 7 internal fn (render_api_key_configured, render_api_key_entry, render_chatgpt_success, render_chatgpt_success_message, render_continue_in_browser, render_pick_mode, render_device_code_login).

fn maybe_open_auth_url_in_browser(request_handle: &AppServerRequestHandle, url: &str)

Purpose: Attempts to open the ChatGPT auth URL in the user’s browser when the app server is running in the same process. This avoids trying to launch a browser from remote server contexts.

Data flow: It receives the app-server request handle and URL. If the handle is not in-process, it returns without doing anything. Otherwise it asks the operating system to open the URL and logs a warning if that fails.

Call relations: start_chatgpt_login calls this after receiving a browser-login URL from the app server.

Call graph: called by 1 (start_chatgpt_login); 3 external calls (matches!, warn!, open).

async fn widget_forced_chatgpt() -> (AuthModeWidget, TempDir)

Purpose: Builds a test AuthModeWidget configured so only ChatGPT login is allowed. This gives tests a realistic widget without touching the user’s real configuration.

Data flow: It creates a temporary Codex home directory, builds test configuration, starts an in-process app server client, and returns a widget plus the temporary directory. The widget starts in pick mode with forced ChatGPT login.

Call relations: Most tests in this module call this helper to avoid repeating setup code.

Call graph: calls 5 internal fn (start, default, default_for_tests, new, test_dummy); 12 external calls (new, default, new, new, new, InProcess, default, cloud_config_bundle_loader_for_storage, default, from_value (+2 more)).

async fn api_key_flow_disabled_when_chatgpt_forced()

Purpose: Checks that starting API-key entry is blocked when the workspace forces ChatGPT login.

Data flow: It creates a forced-ChatGPT widget, tries to start API-key entry, then checks that the error message is the disabled message and the state remains pick mode.

Call relations: This test exercises start_api_key_entry and the disabled-login path.

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

async fn saving_api_key_is_blocked_when_chatgpt_forced()

Purpose: Checks that even a direct save attempt cannot bypass a forced ChatGPT-only setting.

Data flow: It creates a forced-ChatGPT widget, calls the API-key save function with a fake key, and verifies that the disabled message appears, the state returns to pick mode, and the login status stays unauthenticated.

Call relations: This test exercises the guard inside save_api_key.

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

async fn existing_non_oauth_chatgpt_login_counts_as_signed_in()

Purpose: Checks that different ChatGPT-compatible credential types are treated as already signed in. This avoids forcing users through login again unnecessarily.

Data flow: For each tested auth mode, it creates a widget, sets the login status, calls the existing-login check, and verifies that the widget moves to ChatGPT success.

Call relations: This test exercises handle_existing_chatgpt_login, which is used before starting ChatGPT or device-code login.

Call graph: 4 external calls (assert!, assert_eq!, AuthMode, widget_forced_chatgpt).

async fn cancel_active_attempt_resets_browser_login_state()

Purpose: Checks that canceling a browser-login attempt clears the error and returns to the picker.

Data flow: It creates a widget, injects an active browser-login state and an error, calls cancel, and verifies that the error is gone and the state is pick mode.

Call relations: This test exercises cancel_active_attempt for the browser-login branch.

Call graph: 4 external calls (assert!, assert_eq!, ChatGptContinueInBrowser, widget_forced_chatgpt).

async fn cancel_active_attempt_notifies_device_code_login()

Purpose: Checks that canceling a device-code login resets the local UI state. It also covers the path where a device-code login has a login ID that can be canceled server-side.

Data flow: It creates a widget, sets a ready device-code state with a login ID and error, calls cancel, and verifies that the local error is cleared and the picker is restored.

Call relations: This test exercises cancel_active_attempt for the device-code branch and uses ContinueWithDeviceCodeState::ready to build the state.

Call graph: calls 1 internal fn (ready); 4 external calls (assert!, assert_eq!, ChatGptDeviceCode, widget_forced_chatgpt).

fn collect_osc8_chars(buf: &Buffer, area: Rect, url: &str) -> String

Purpose: Reads a test buffer and gathers the characters wrapped in a specific terminal hyperlink. This is a test helper for checking OSC 8 hyperlink rendering.

Data flow: It receives a buffer, area, and URL. It scans every cell in the area, looks for the hyperlink open and close escape sequences for that URL, and concatenates the visible characters found inside them.

Call relations: Hyperlink tests call this after rendering or manually marking a buffer to verify exactly which characters became clickable.

Call graph: 6 external calls (bottom, left, right, top, new, format!).

fn continue_in_browser_renders_osc8_hyperlink()

Purpose: Checks that the browser-login screen marks the full auth URL as one terminal hyperlink, even when the URL wraps across lines.

Data flow: It creates a widget in browser-login state, renders into a narrow buffer, collects hyperlink-wrapped characters, and asserts that they equal the original URL.

Call relations: This test exercises render_continue_in_browser, which calls mark_url_hyperlink after drawing the URL.

Call graph: 7 external calls (empty, new, assert_eq!, new, ChatGptContinueInBrowser, collect_osc8_chars, widget_forced_chatgpt).

fn auth_widget_suppresses_animations_when_device_code_is_visible()

Purpose: Checks that animations are suppressed when a ready device-code login is visible. This helps keep the copyable code and URL steady.

Data flow: It creates a widget, sets a ready device-code state, calls the animation-suppression query, and expects true.

Call relations: This test exercises should_suppress_animations with a state built by ContinueWithDeviceCodeState::ready.

Call graph: calls 1 internal fn (ready); 4 external calls (assert_eq!, new, ChatGptDeviceCode, widget_forced_chatgpt).

fn auth_widget_suppresses_animations_while_requesting_device_code()

Purpose: Checks that animations are also suppressed while the device-code request is still pending.

Data flow: It creates a widget, sets a pending device-code state, calls the animation-suppression query, and expects true.

Call relations: This test exercises should_suppress_animations with a state built by ContinueWithDeviceCodeState::pending.

Call graph: calls 1 internal fn (pending); 4 external calls (assert_eq!, new, ChatGptDeviceCode, widget_forced_chatgpt).

async fn device_code_login_completion_advances_to_success_message()

Purpose: Checks that a successful completion notification for the active device-code login advances the UI to the ChatGPT success message.

Data flow: It creates a widget in ready device-code state, sends a matching successful completion notification, and verifies that the sign-in state becomes the success-message state.

Call relations: This test exercises on_account_login_completed and its login-ID matching logic.

Call graph: calls 1 internal fn (ready); 3 external calls (assert!, ChatGptDeviceCode, widget_forced_chatgpt).

fn mark_url_hyperlink_wraps_cyan_underlined_cells()

Purpose: Checks that styled URL cells are wrapped in terminal hyperlink codes and unrelated cells are left alone.

Data flow: It creates a buffer, manually writes cyan underlined characters, leaves one plain character, calls mark_url_hyperlink, and verifies only the styled characters became hyperlink text.

Call relations: This test calls the local hyperlink wrapper directly and uses collect_osc8_chars to inspect the result.

Call graph: calls 1 internal fn (mark_url_hyperlink); 4 external calls (empty, new, assert_eq!, collect_osc8_chars).

fn mark_url_hyperlink_sanitizes_control_chars()

Purpose: Checks that unsafe control characters in a URL are removed before building terminal hyperlink escape sequences. This prevents a malicious URL from injecting terminal commands.

Data flow: It creates one styled buffer cell, passes a URL containing escape and bell control characters to mark_url_hyperlink, and verifies the stored symbol contains a sanitized URL but not the raw dangerous sequence.

Call relations: This test calls mark_url_hyperlink directly to validate the safety behavior provided by the shared hyperlink helper.

Call graph: calls 1 internal fn (mark_url_hyperlink); 3 external calls (empty, new, assert!).

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Purpose: Draws the trust prompt into the terminal screen. It turns the widget’s stored state into visible text, warnings, choices, and optional error messages.

Data flow: It reads the widget’s current directory, trust target, highlighted option, Windows sandbox hint flag, and error text. From that, it builds a vertical column of terminal UI elements: location text, an optional Git-root warning, the trust explanation, the two selectable rows, any error, and the confirm-key hint. It writes the finished display into the terminal buffer for the given screen area.

Call relations: The terminal UI framework calls this when the onboarding screen needs to be painted. Inside, it uses shared rendering helpers to create rows, spacing, wrapping text, and insets, and it uses selection_option_row so the two choices look consistent with other selection lists.

Call graph: calls 3 internal fn (tlbr, new, selection_option_row); 4 external calls (from, new, format!, vec!).

fn handle_key_event(&mut self, key_event: KeyEvent)

Purpose: Turns a keyboard event into a change on the trust screen. It lets the user move between choices, accept trust, or quit.

Data flow: It receives one key event. If the event is only a key release, it ignores it so the same physical key press is not counted twice. For movement keys, it changes the highlighted choice. For direct selection or confirm keys, it calls either the trust path or the quit path, which updates the widget’s stored decision.

Call relations: The onboarding screen calls this whenever the user presses a key. This function is the central dispatcher for keyboard behavior and hands the actual state changes to TrustDirectoryWidget::handle_trust or TrustDirectoryWidget::handle_quit.

Call graph: calls 2 internal fn (handle_quit, handle_trust).

fn get_step_state(&self) -> StepState

Purpose: Reports whether this onboarding step is still waiting for the user or has finished. The surrounding onboarding flow uses this to know whether it can move on.

Data flow: It reads whether a trust selection has been recorded or whether quitting has been requested. If either is true, it returns Complete; otherwise it returns InProgress.

Call relations: The onboarding controller asks this while coordinating steps. It does not change anything itself; it simply summarizes the widget’s current state for the larger flow.

fn handle_trust(&mut self)

Purpose: Records that the user chose to trust the directory. It also clears any previous error so the screen can proceed cleanly.

Data flow: It takes the existing widget state, sets the highlighted choice to Trust, removes any error message, and stores Trust as the selected answer. The result is that the step is now considered complete with a positive trust choice.

Call relations: TrustDirectoryWidget::handle_key_event calls this when the user chooses the trust option, either through a shortcut or by confirming while “Yes, continue” is highlighted.

Call graph: called by 1 (handle_key_event).

fn handle_quit(&mut self)

Purpose: Records that the user chose not to continue. This is the safe exit path when the user does not want to trust the directory.

Data flow: It takes the existing widget state, moves the highlight to Quit, and sets the should_quit flag to true. After this, the surrounding app can see that onboarding should end by quitting rather than continuing.

Call relations: TrustDirectoryWidget::handle_key_event calls this when the user chooses “No, quit,” presses a quit key, presses a cancel key, or confirms while the quit option is highlighted.

Call graph: called by 1 (handle_key_event).

fn should_quit(&self) -> bool

Purpose: Answers whether the user has chosen to quit from this trust prompt. Other code can call it instead of reading the internal flag directly.

Data flow: It reads the widget’s should_quit field and returns that boolean value unchanged. It does not update the screen or modify any state.

Call relations: This is a small public accessor for the wider onboarding flow. After keyboard handling has possibly called handle_quit, other code can use this function to decide whether to stop the application.

fn widget(error: Option<String>) -> TrustDirectoryWidget

Purpose: Builds a standard test version of TrustDirectoryWidget. It avoids repeating the same setup in every rendering test.

Data flow: It receives an optional error message. It creates a widget set to /workspace/project, with trust and current directory matching, the trust option highlighted, no quit request, and the supplied error. The completed widget is returned to the test.

Call relations: The snapshot tests call this helper before drawing the screen. It keeps those tests focused on what changes in the display rather than on boilerplate setup.

Call graph: 1 external calls (from).

fn release_event_does_not_change_selection()

Purpose: Checks that key release events do not accidentally trigger a selection. This prevents one physical key press from being treated as multiple actions.

Data flow: It creates a widget with the quit option highlighted and no selection. It sends an Enter key release event and verifies that no selection was made. Then it sends a normal Enter key press and verifies that the widget switches into the quit state.

Call relations: This test exercises TrustDirectoryWidget::handle_key_event. It confirms the early return for release events and then confirms that an actual key press still reaches the normal quit behavior.

Call graph: 4 external calls (new, from, assert!, assert_eq!).

fn renders_snapshot_for_git_repo()

Purpose: Checks that the normal trust prompt renders in the expected shape. A snapshot test compares the drawn terminal output against a saved reference image made of text.

Data flow: It builds a standard widget without an error, creates a fake terminal of a fixed size, asks the widget to render into it, and compares the final terminal contents with the saved snapshot. The test fails if the visible screen changes unexpectedly.

Call relations: This test calls the shared tests::widget helper and then invokes TrustDirectoryWidget::render_ref through the terminal drawing callback. It protects the user-facing layout from accidental changes.

Call graph: calls 1 internal fn (new); 3 external calls (assert_snapshot!, new, widget).

fn renders_snapshot_for_trust_error()

Purpose: Checks that the trust prompt renders correctly when an error message is present. This matters because failure text can be long and must still be readable in the terminal.

Data flow: It builds a widget with a realistic trust-setting error, creates a fake terminal with enough height, renders the widget, and compares the output with a saved snapshot. The result is a pass or fail depending on whether the display matches the expected error layout.

Call relations: This test uses tests::widget to create the screen state and then exercises TrustDirectoryWidget::render_ref. It specifically covers the branch where the renderer shows red wrapped error text.

Call graph: calls 1 internal fn (new); 3 external calls (assert_snapshot!, new, widget).

fn label(self) -> &'static str

Purpose: Returns the human-readable text for each action button, such as importing selected items or cancelling. This keeps the menu wording in one place instead of scattering strings through the screen code.

Data flow: It receives one action option → matches it to the text the user should see → returns that text as a fixed string.

Call relations: This is the small vocabulary helper for the action menu. When the screen is drawn, the render code can ask each action what label should appear.

async fn run_external_agent_config_migration_prompt(
    tui: &mut Tui,
    items: &[ExternalAgentConfigMigrationItem],
    selected_items: &[ExternalAgentConfigMigrationItem],
    error: Option<&str>

Purpose: Shows the migration prompt, keeps it updated while the user presses keys or the terminal resizes, and returns the user's final choice. This is the main doorway into this prompt from the rest of the app.

Data flow: It receives the terminal UI object, all possible items, the initially selected items, and an optional error message → builds a screen, draws it, listens to terminal events, and updates the screen state → returns either a list of items to import or a skip result.

Call relations: It is called by the higher-level migration prompt handler. It creates an ExternalAgentConfigMigrationScreen, asks the TUI to draw it, feeds keyboard events into handle_key, redraws on draw or resize events, and reads the screen outcome when the screen says it is done.

Call graph: calls 1 internal fn (new); called by 1 (handle_external_agent_config_migration_prompt); 4 external calls (draw, event_stream, frame_requester, pin!).

fn proceed_enabled(&self) -> bool

Purpose: Answers whether the user is currently allowed to proceed with an import. Proceeding is only allowed when at least one item is selected.

Data flow: It reads the screen's item selections → counts how many are enabled → returns true if that count is greater than zero.

Call relations: available_actions asks this before deciding whether the “Import selected” action should be shown. That prevents an empty import from being chosen.

Call graph: calls 1 internal fn (selected_count); called by 1 (available_actions).

fn first_available_action(&self) -> ActionMenuOption

Purpose: Finds the first action the user can choose right now. It is used when focus needs a safe place to land.

Data flow: It builds the current action list → takes the first entry if one exists → otherwise falls back to the Back action.

Call relations: When selection changes or the screen returns to summary mode, other navigation helpers use this to keep the highlighted button valid.

Call graph: calls 1 internal fn (available_actions); called by 3 (back_to_summary, move_down, normalize_highlighted_action).

fn last_available_action(&self) -> ActionMenuOption

Purpose: Finds the last action the user can choose right now. It supports wraparound keyboard movement.

Data flow: It builds the current action list → takes the last entry if one exists → otherwise falls back to the Back action.

Call relations: move_up uses this when the user moves above the first action or leaves the item list toward the action area.

Call graph: calls 1 internal fn (available_actions); called by 1 (move_up).

fn previous_available_action(&self, action: ActionMenuOption) -> Option<ActionMenuOption>

Purpose: Finds the action immediately before a given action in the current menu. This lets the highlighted button move upward through the available choices.

Data flow: It builds the current action list → locates the current action → steps one position backward if possible → returns that earlier action or nothing.

Call relations: move_up calls this while navigating the action menu. If there is no earlier action, move_up decides whether to wrap around or move focus elsewhere.

Call graph: calls 1 internal fn (available_actions); called by 1 (move_up).

fn next_available_action(&self, action: ActionMenuOption) -> Option<ActionMenuOption>

Purpose: Finds the action immediately after a given action in the current menu. This lets the highlighted button move downward through the available choices.

Data flow: It builds the current action list → locates the current action → steps one position forward if possible → returns that later action or nothing.

Call relations: move_down calls this while navigating the action menu. If there is no later action, move_down wraps or moves focus back to the item list.

Call graph: calls 1 internal fn (available_actions); called by 1 (move_down).

fn available_actions(&self) -> Vec<ActionMenuOption>

Purpose: Builds the list of action buttons that should exist in the current view. For example, it hides “Import selected” when nothing is selected.

Data flow: It reads the current view and selection state → chooses the valid actions for summary or customize mode → returns them in display order.

Call relations: Navigation, shortcuts, and highlight cleanup all depend on this function so they agree with what the user can actually see and choose.

Call graph: calls 1 internal fn (proceed_enabled); called by 6 (first_available_action, last_available_action, next_available_action, normalize_highlighted_action, previous_available_action, select_numbered_action); 2 external calls (new, vec!).

fn normalize_highlighted_action(&mut self)

Purpose: Makes sure the currently highlighted action is still valid. This matters when a selection change removes an action, such as hiding “Import selected” after all items are deselected.

Data flow: It reads the current highlighted action and the current valid action list → if the highlight is no longer allowed, replaces it with the first valid action → changes only the highlight.

Call relations: set_all_enabled and toggle_selected_item call this after changing selections, so the keyboard focus never points at a vanished button.

Call graph: calls 2 internal fn (available_actions, first_available_action); called by 2 (set_all_enabled, toggle_selected_item).

fn display_description(item: &ExternalAgentConfigMigrationItem) -> String

Purpose: Turns a migration item's technical description into friendlier text for the terminal prompt. It also shortens file paths relative to a project when possible.

Data flow: It receives one migration item → changes wording from “Migrate” to “Import”, reformats known path patterns, and adds plugin counts when plugin details exist → returns the text shown to the user.

Call relations: The customize-line builder uses this when it creates the detail line under each item. It relies on display_path_for so paths are easier to read.

Call graph: 1 external calls (format!).

fn new(
        request_frame: FrameRequester,
        items: &[ExternalAgentConfigMigrationItem],
        selected_items: &[ExternalAgentConfigMigrationItem],
        error: Option<String>,
    ) ->

Purpose: Creates a fresh migration prompt screen with its starting selections, grouped summary data, focus, and default outcome. This is the setup step before drawing or handling keys.

Data flow: It receives a frame requester, all items, initially selected items, and an optional error → groups the items, marks each item enabled or disabled, chooses initial focus and highlighted action → returns a ready-to-use screen.

Call relations: The top-level prompt runner and tests call this first. It uses the migration model helpers to build summary groups, then normalizes the highlighted action so the first draw starts in a valid state.

Call graph: calls 1 internal fn (external_agent_config_migration_groups); called by 12 (run_external_agent_config_migration_prompt, control_exit_shortcuts_cancel_prompt, customize_action_snapshot, customize_snapshot, empty_selection_enter_opens_customize_instead_of_proceeding, escape_skips_prompt, numeric_shortcuts_choose_actions, numeric_shortcuts_follow_visible_actions_when_proceed_is_disabled, proceed_returns_selected_items, prompt_snapshot (+2 more)); 1 external calls (iter).

fn plugin_detail_lines(plugin_groups: &[PluginsMigration]) -> Vec<Line<'static>>

Purpose: Creates a short preview of plugin details for display under a plugin import item. It deliberately limits the list so the prompt does not become huge.

Data flow: It receives plugin groups grouped by marketplace → keeps at most three marketplaces and at most two plugin names per marketplace, adding “more” counts when needed → returns formatted terminal text lines.

Call relations: The customize view uses this when an item has plugin migration details. It turns nested plugin data into readable extra lines.

Call graph: 4 external calls (from, iter, len, format!).

fn is_done(&self) -> bool

Purpose: Reports whether the prompt has finished. The event loop uses this as its stop condition.

Data flow: It reads the screen's done flag → returns that true-or-false value.

Call relations: run_external_agent_config_migration_prompt checks this repeatedly while waiting for events. finish_with is what eventually changes the flag.

fn outcome(&self) -> ExternalAgentConfigMigrationOutcome

Purpose: Returns the final answer chosen by the user. The answer is either to proceed with selected items or skip.

Data flow: It reads the stored outcome → clones it so the caller can own the result → returns that copy.

Call relations: After the prompt loop ends, the runner calls this to hand the result back to the migration flow.

Call graph: 1 external calls (clone).

fn finish_with(&mut self, outcome: ExternalAgentConfigMigrationOutcome)

Purpose: Ends the prompt with a specific result. It is the shared finalization step for both importing and skipping.

Data flow: It receives an outcome → stores it, marks the screen done, and asks the terminal to redraw → leaves the screen ready for the outer loop to stop.

Call relations: proceed and skip both call this. The scheduled frame lets the UI catch up after the state changes.

Call graph: calls 1 internal fn (schedule_frame); called by 2 (proceed, skip).

fn proceed(&mut self)

Purpose: Finishes the prompt by choosing to import the currently selected items. This is what happens when the user confirms the import action.

Data flow: It reads all enabled items → wraps them in a Proceed outcome → passes that outcome to finish_with.

Call relations: confirm_selection calls this when the highlighted action is Proceed. It hands final control to finish_with.

Call graph: calls 2 internal fn (finish_with, selected_items); called by 1 (confirm_selection); 1 external calls (Proceed).

fn skip(&mut self)

Purpose: Finishes the prompt by cancelling the import. This gives the user and the event loop a clean way to exit without changing selections further.

Data flow: It creates a Skip outcome → passes it to finish_with → the screen becomes done.

Call relations: confirm_selection calls this for the Cancel action, and handle_key calls it for escape or control-exit shortcuts.

Call graph: calls 1 internal fn (finish_with); called by 2 (confirm_selection, handle_key).

fn selected_items(&self) -> Vec<ExternalAgentConfigMigrationItem>

Purpose: Collects the migration items that are currently enabled. This is the final shopping basket used when the user imports.

Data flow: It scans the screen's item list → keeps only enabled entries → clones and returns the underlying migration items.

Call relations: proceed calls this just before finishing, so the outcome contains exactly what the user left selected.

Call graph: called by 1 (proceed).

fn selected_count(&self) -> usize

Purpose: Counts how many items are currently selected. This is used to decide whether importing is possible.

Data flow: It scans all item selections → counts the enabled ones → returns the number.

Call relations: proceed_enabled calls this, and available_actions uses that result to show or hide the Proceed action.

Call graph: called by 1 (proceed_enabled).

fn group_selection_marker(
        &self,
        group: &ExternalAgentConfigMigrationGroupModel,
    ) -> &'static str

Purpose: Chooses the checkbox marker for a summary group. It can show empty, checked, or partly checked.

Data flow: It receives a group → checks how many items in that group are enabled → returns a marker: blank for none, x for all, or dash for some.

Call relations: The summary-line builder uses this to make grouped selection status easy to understand at a glance.

fn set_all_enabled(&mut self, enabled: bool)

Purpose: Turns every migration item on or off at once. This powers the “select all” and “select none” keyboard shortcuts in customize mode.

Data flow: It receives a desired enabled value → applies it to every item, clears any error, fixes the highlighted action, and requests a redraw → the whole selection changes together.

Call relations: handle_key calls this for the customize shortcuts. After changing the list, it uses normalize_highlighted_action so the action menu stays consistent.

Call graph: calls 2 internal fn (normalize_highlighted_action, schedule_frame); called by 1 (handle_key).

fn toggle_selected_item(&mut self)

Purpose: Flips the enabled state of the currently highlighted item. It only works in the customize view while focus is on the item list.

Data flow: It checks the view, focus, and selected item index → if an item is actually selected, switches it from on to off or off to on, clears errors, fixes the action highlight, and requests a redraw.

Call relations: confirm_selection calls this when Enter is pressed on an item, and handle_key calls it for the space bar in customize mode.

Call graph: calls 2 internal fn (normalize_highlighted_action, schedule_frame); called by 2 (confirm_selection, handle_key).

fn customize(&mut self)

Purpose: Switches from the summary view into the detailed customize view. It sets focus to the item list so the user can immediately review individual choices.

Data flow: It changes the view, selects the first item if there is one, resets scrolling, moves focus to items, highlights Back as the available action, and requests a redraw.

Call relations: confirm_selection calls this when the user chooses Customize, and handle_key calls it for the summary shortcut.

Call graph: calls 1 internal fn (schedule_frame); called by 2 (confirm_selection, handle_key).

fn back_to_summary(&mut self)

Purpose: Returns from the detailed customize view to the shorter summary view. It resets navigation so the action menu is ready again.

Data flow: It changes the view to summary, selects the first group if there is one, resets scrolling, moves focus to actions, picks the first valid action, and requests a redraw.

Call relations: confirm_selection calls this for the Back action, and handle_key calls it for the customize shortcut or Escape.

Call graph: calls 2 internal fn (first_available_action, schedule_frame); called by 2 (confirm_selection, handle_key).

fn move_up(&mut self)

Purpose: Moves the keyboard focus upward. Depending on the current view, this can move between action buttons, move through items, or jump between the item list and actions.

Data flow: It reads the current view, focus, selected item, and highlighted action → updates them to the previous logical place, wrapping when appropriate → keeps the selected item visible and requests a redraw.

Call relations: handle_key calls this for Up or k. It uses the action-navigation helpers and ensure_selected_item_visible so movement and scrolling stay in sync.

Call graph: calls 4 internal fn (ensure_selected_item_visible, last_available_action, previous_available_action, schedule_frame); called by 1 (handle_key).

fn move_down(&mut self)

Purpose: Moves the keyboard focus downward. It mirrors move_up for Down or j navigation.

Data flow: It reads the current view, focus, selected item, and highlighted action → updates them to the next logical place, wrapping when appropriate → keeps the selected item visible and requests a redraw.

Call relations: handle_key calls this for Down or j. It uses next and first action helpers plus ensure_selected_item_visible.

Call graph: calls 4 internal fn (ensure_selected_item_visible, first_available_action, next_available_action, schedule_frame); called by 1 (handle_key).

fn confirm_selection(&mut self)

Purpose: Performs the action represented by the current focus. Enter either toggles an item or activates the highlighted action button.

Data flow: It checks whether focus is on items or actions → toggles the item if on items, or dispatches to proceed, customize, skip, or back_to_summary if on actions → updates the screen or finishes the prompt.

Call relations: handle_key calls this for Enter, and select_numbered_action calls it after moving the highlight to a numbered action.

Call graph: calls 5 internal fn (back_to_summary, customize, proceed, skip, toggle_selected_item); called by 2 (handle_key, select_numbered_action).

fn handle_key(&mut self, key_event: KeyEvent)

Purpose: Translates raw key presses into screen behavior. This is where keyboard controls become navigation, selection changes, view changes, or cancellation.

Data flow: It receives a key event → ignores key-release events, checks control-exit shortcuts, then matches the key code to the correct screen operation → changes state and often schedules a redraw through the called operation.

Call relations: The top-level prompt runner feeds all terminal key events here. This function delegates almost everything to smaller helpers such as move_up, move_down, customize, set_all_enabled, and confirm_selection.

Call graph: calls 10 internal fn (back_to_summary, confirm_selection, customize, move_down, move_up, select_numbered_action, set_all_enabled, skip, toggle_selected_item, is_ctrl_exit_combo).

fn select_numbered_action(&mut self, number: char)

Purpose: Lets number keys choose visible action buttons. For example, pressing 1 activates the first currently available action.

Data flow: It receives a digit character → converts it to a zero-based menu index, looks up that action, moves focus and highlight to it, then confirms it → may change view or finish the prompt.

Call relations: handle_key calls this for number keys. It uses available_actions so shortcuts always match the actions currently visible to the user.

Call graph: calls 2 internal fn (available_actions, confirm_selection); called by 1 (handle_key).

fn ensure_selected_item_visible(&mut self)

Purpose: Adjusts scrolling so the currently selected item stays on screen. It is like keeping the cursor inside the visible window.

Data flow: It reads the selected item and current scroll position → finds where that item appears in the rendered line list → moves scroll_top up or down if needed.

Call relations: move_up and move_down call this after changing selection. It uses render_line_count and selected_render_line_index to reason in terms of visible lines, not just items.

Call graph: calls 2 internal fn (render_line_count, selected_render_line_index); called by 2 (move_down, move_up).

fn render_line_count(&self) -> usize

Purpose: Counts how many text lines the current view would render. This supports scroll calculations.

Data flow: It builds the render-line list for the current view → returns the number of lines.

Call relations: ensure_selected_item_visible calls this when it decides how much content can be scrolled through.

Call graph: calls 1 internal fn (build_render_lines); called by 1 (ensure_selected_item_visible).

fn selected_render_line_index(&self, selected_item_idx: usize) -> usize

Purpose: Finds the rendered line that corresponds to a selected item. This bridges item selection and the actual text layout.

Data flow: It receives an item index → builds the current render-line list, searches for the line tied to that item, and returns the line position → falls back to the item index if not found.

Call relations: ensure_selected_item_visible calls this to know whether the selected item is above or below the visible area.

Call graph: calls 1 internal fn (build_render_lines); called by 1 (ensure_selected_item_visible).

fn section_title(cwd: Option<&std::path::Path>) -> Line<'static>

Purpose: Creates the heading used to separate home-level items from project-specific items in the customize view.

Data flow: It receives an optional current working directory path → returns a styled line saying either “Current project” with the path or “Home”.

Call relations: build_customize_render_lines calls this whenever it starts a new item scope.

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

fn build_render_lines(&self) -> Vec<RenderLineEntry>

Purpose: Builds the text-line model for whichever view is active. This gives scrolling and rendering a common source of truth.

Data flow: It reads the current view → delegates to the summary or customize line builder → returns the list of render-line entries.

Call relations: render_line_count and selected_render_line_index call this when they need to understand the current screen layout.

Call graph: calls 2 internal fn (build_customize_render_lines, build_summary_render_lines); called by 2 (render_line_count, selected_render_line_index).

fn build_summary_render_lines(&self) -> Vec<RenderLineEntry>

Purpose: Creates the compact summary text lines. Each group gets a checkbox-style status line and a description line.

Data flow: It reads the grouped migration data and current selections → builds display entries for each group, including selection markers → returns the list of summary lines.

Call relations: build_render_lines calls this when the screen is in summary view. The render module can then draw these entries.

Call graph: called by 1 (build_render_lines).

fn build_customize_render_lines(&self) -> Vec<RenderLineEntry>

Purpose: Creates the detailed item-by-item text lines for the customize view. It includes section headings, checkboxes, descriptions, optional extra details, and plugin previews.

Data flow: It scans every migration item in order → inserts a new section when the project scope changes, adds the item label and description, adds model-provided details and plugin lines when present → returns the full customize layout.

Call relations: build_render_lines calls this in customize mode. It works with item-label/detail helpers, section_title, display_description, and plugin_detail_lines to make raw migration data readable.

Call graph: calls 1 internal fn (external_agent_config_migration_item_detail); called by 1 (build_render_lines); 6 external calls (from, plugin_detail_lines, section_title, new, format!, vec!).

fn is_ctrl_exit_combo(key_event: KeyEvent) -> bool

Purpose: Detects terminal-style exit shortcuts: Control-C and Control-D. These should cancel the prompt quickly.

Data flow: It receives a key event → checks whether the key is c or d and whether the Control modifier is held → returns true or false.

Call relations: handle_key calls this before normal key handling. If it returns true, the screen skips the prompt.

Call graph: called by 1 (handle_key); 1 external calls (matches!).

fn sample_plugin_details() -> codex_app_server_protocol::MigrationDetails

Purpose: Builds realistic plugin migration details for tests. The sample includes enough marketplaces and plugin names to test truncation and “more” text.

Data flow: It creates several plugin marketplace groups with plugin names → wraps them in a migration details structure → returns that test data.

Call relations: sample_items uses this to attach plugin details to a sample plugin migration item.

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

fn sample_project_root() -> PathBuf

Purpose: Provides a platform-appropriate sample project path for tests. It returns a Windows path on Windows and a Unix-style path elsewhere.

Data flow: It checks the compile-time operating system configuration → creates the matching path buffer → returns it.

Call relations: sample_project_path and sample_items use this so snapshots match the operating system's path style.

Call graph: 1 external calls (from).

fn sample_project_path(path: &str) -> String

Purpose: Builds a sample path inside the fake project root. This keeps test paths consistent.

Data flow: It receives a relative path string → joins it to the sample project root → returns it as display text.

Call relations: sample_items calls this when building item descriptions that contain project-local files.

Call graph: 1 external calls (sample_project_root).

fn sample_items() -> Vec<ExternalAgentConfigMigrationItem>

Purpose: Creates a representative set of migration items for tests. The items cover global config, sessions, plugins, and project instructions.

Data flow: It builds paths and detail structures → creates several ExternalAgentConfigMigrationItem values with different types and scopes → returns them in a vector.

Call relations: Nearly all tests call this to start from the same realistic prompt data.

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

fn render_screen(
        screen: &ExternalAgentConfigMigrationScreen,
        width: u16,
        height: u16,
    ) -> String

Purpose: Renders a screen into plain text for snapshot tests. This lets tests compare what the terminal would show without needing a real terminal window.

Data flow: It receives a screen plus width and height → creates a fake VT100 terminal backend, renders the widget, flushes the terminal, trims line endings → returns the visible screen as a string.

Call relations: The snapshot tests call this after constructing or changing a screen, then compare the result to stored snapshots.

Call graph: calls 2 internal fn (with_options, new); 1 external calls (new).

fn prompt_snapshot()

Purpose: Checks that the default summary prompt looks as expected. This protects the user-facing layout from accidental changes.

Data flow: It creates sample items and a new screen with all items selected → renders it at a fixed terminal size → compares the text to the appropriate stored snapshot.

Call relations: This test exercises ExternalAgentConfigMigrationScreen::new and render_screen in the starting summary state.

Call graph: calls 2 internal fn (new, test_dummy); 3 external calls (assert_snapshot!, render_screen, sample_items).

fn customize_snapshot()

Purpose: Checks that the customize view looks as expected. It verifies the detailed item list and extra details.

Data flow: It creates a screen, switches it to customize mode, renders it, and compares the output to a stored snapshot.

Call relations: This test uses the screen's customize method and render_screen to cover the detailed view.

Call graph: calls 2 internal fn (new, test_dummy); 3 external calls (assert_snapshot!, render_screen, sample_items).

fn customize_action_snapshot()

Purpose: Checks the customize view when focus is on the action area instead of the item list. This protects the visual highlight behavior.

Data flow: It creates a screen, enters customize mode, moves focus upward to the action button, renders, and compares the output to a snapshot.

Call relations: This test exercises customize, move_up, and render_screen together.

Call graph: calls 2 internal fn (new, test_dummy); 3 external calls (assert_snapshot!, render_screen, sample_items).

fn proceed_returns_selected_items()

Purpose: Verifies that pressing Enter on the default prompt proceeds with all selected items. This confirms the happy path.

Data flow: It creates a screen with all items selected → sends an Enter key event → checks that the screen is done and that the outcome contains all items.

Call relations: This test drives handle_key, which reaches confirm_selection and proceed.

Call graph: calls 2 internal fn (new, test_dummy); 4 external calls (new, assert!, assert_eq!, sample_items).

fn toggle_item_then_proceed_keeps_remaining_selection()

Purpose: Verifies that deselecting one item in customize mode affects the final import list. This ensures user customization is honored.

Data flow: It creates a selected screen → enters customize mode, toggles the first item off, returns to summary, chooses the first action → checks that the outcome excludes only that item.

Call relations: This test exercises handle_key paths for customize, toggle_selected_item, back_to_summary, numeric action selection, and proceed.

Call graph: calls 2 internal fn (new, test_dummy); 5 external calls (Char, new, assert!, assert_eq!, sample_items).

fn escape_skips_prompt()

Purpose: Verifies that Escape cancels the prompt from the summary view. This protects an expected terminal escape behavior.

Data flow: It creates a screen → sends an Escape key event → checks that the screen is done with a Skip outcome.

Call relations: This test drives handle_key into the skip path.

Call graph: calls 2 internal fn (new, test_dummy); 4 external calls (new, assert!, assert_eq!, sample_items).

fn numeric_shortcuts_follow_visible_actions_when_proceed_is_disabled()

Purpose: Verifies that number shortcuts match the currently visible actions when importing is not allowed. This prevents shortcut numbers from activating hidden buttons.

Data flow: It creates a screen, enters customize mode, deselects all items, returns to summary, then presses 1 → checks that this opens customize instead of proceeding.

Call relations: This test covers set_all_enabled, back_to_summary, available_actions, and select_numbered_action through handle_key.

Call graph: calls 2 internal fn (new, test_dummy); 4 external calls (Char, new, assert_eq!, sample_items).

fn empty_selection_enter_opens_customize_instead_of_proceeding()

Purpose: Verifies that Enter does not proceed when no items are initially selected. Instead, the first available action is to customize.

Data flow: It creates a screen with no selected items → sends Enter → checks that the prompt is still open and now in customize view.

Call relations: This test depends on new normalizing the highlighted action and handle_key confirming the visible Customize action.

Call graph: calls 2 internal fn (new, test_dummy); 4 external calls (new, assert!, assert_eq!, sample_items).

fn control_exit_shortcuts_cancel_prompt()

Purpose: Verifies that Control-C and Control-D cancel the prompt. These are common terminal shortcuts for stopping or exiting.

Data flow: For each shortcut, it creates a fresh screen → sends the control key event → checks that the screen is done with Skip.

Call relations: This test covers is_ctrl_exit_combo through handle_key.

Call graph: calls 2 internal fn (new, test_dummy); 5 external calls (Char, new, assert!, assert_eq!, sample_items).

fn numeric_shortcuts_choose_actions()

Purpose: Verifies that number keys activate Proceed, Customize, Back, and Skip in the expected positions. This protects keyboard-only use of the prompt.

Data flow: It creates separate screens for each shortcut scenario → sends number key events → checks the resulting outcome or view.

Call relations: This test drives select_numbered_action through handle_key and confirms it uses available_actions correctly.

Call graph: calls 2 internal fn (new, test_dummy); 4 external calls (Char, new, assert_eq!, sample_items).

fn summary_does_not_toggle_selection()

Purpose: Verifies that pressing space in the summary view does not change item selection. Toggling is only allowed in customize mode.

Data flow: It creates a fully selected screen → sends a space key event → checks that selected_items still returns all sample items.

Call relations: This test exercises handle_key's summary behavior and protects the guard inside toggle_selected_item from being bypassed.

Call graph: calls 2 internal fn (new, test_dummy); 4 external calls (Char, new, assert_eq!, sample_items).

fn render_items(&self, area: Rect, buf: &mut Buffer)

Purpose: Draws the scrollable list of migration items inside a given rectangle of the terminal. It makes sure the selected item stays visible and visually marks the current choice so the user can tell where they are.

Data flow: It receives a screen area and a mutable terminal buffer, then reads the screen’s prepared render lines, current scroll position, selected item, and focus state. It chooses which rows fit, adjusts the starting row if the selected item would otherwise be off-screen, styles selected rows brightly, dims non-item helper rows, trims overly long lines with an ellipsis, and writes each visible row into the buffer. It does not return a value; the visible terminal buffer is the result.

Call relations: This is the list-painting helper used by ExternalAgentConfigMigrationScreen::render_ref when the full screen is being drawn. It delegates only the final safety step for too-long text to truncate_line_with_ellipsis_if_overflow, so the list stays inside its assigned space.

Call graph: calls 1 internal fn (truncate_line_with_ellipsis_if_overflow); called by 1 (render_ref).

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Purpose: Draws the whole migration screen: title, introduction, error message, item list, action choices, and footer key hints. This is the main rendering entry used when the terminal UI asks this screen to paint itself.

Data flow: It receives the outer terminal area and a mutable buffer. It clears the area, adds padding, decides which introduction and title to show based on the current view, measures how much space each section needs, splits the screen into rectangles, and renders each section into its rectangle. It reads the current error, list contents, selected count, available actions, focus area, highlighted action, and view mode. The output is a fully updated terminal buffer ready to be displayed.

Call relations: The terminal UI rendering system calls this through the WidgetRef interface, which means the screen can be drawn like a standard terminal widget. During that draw, it calls render_items for the central item list, uses layout helpers to divide the screen, uses selection_option_row_with_dim to draw action rows consistently, and uses key_hint helpers so shortcut labels look like the rest of the app.

Call graph: calls 3 internal fn (render_items, vh, selection_option_row_with_dim); 10 external calls (Fill, Length, vertical, from, new, inset, format!, repeat_n, from, vec!).

fn all() -> [Self; 2]

Purpose: Returns the two choices that can appear in the migration menu. It gives the renderer a fixed, ordered list so the menu is always shown consistently.

Data flow: Nothing is passed in. The function creates a small two-item array containing the new-model choice followed by the existing-model choice. That array is returned for menu drawing.

Call relations: When the screen draws the menu, render_menu asks this function for the available choices, then turns each one into a visible row.

Call graph: called by 1 (render_menu).

fn label(self) -> &'static str

Purpose: Turns one internal menu choice into the text the user sees. This keeps the display wording in one place instead of scattering strings through the drawing code.

Data flow: It receives a menu option value. It matches that value to either "Try new model" or "Use existing model". The matching text is returned.

Call relations: The menu renderer uses this when building each row, so the internal choice and the visible label stay connected.

fn migration_copy_for_models(
    current_model: &str,
    target_model: &str,
    model_link: Option<String>,
    migration_copy: Option<String>,
    migration_markdown: Option<String>,
    target_di

Purpose: Builds the message content for the migration prompt from model names, optional marketing copy, links, markdown, and opt-out rules. It is the main place where raw model information becomes user-facing text.

Data flow: Inputs include the current model, target model, optional link, optional custom copy, optional markdown template, display name, description, and whether the user may opt out. If markdown is supplied, it fills in the model placeholders and returns markdown-only prompt content. Otherwise it creates a heading, explanatory lines, optional learn-more link text, and either opt-out wording or a simple continue instruction. The result is a ModelMigrationCopy object used by the screen.

Call relations: The runtime prompt receives this prepared copy before drawing. The tests also call it to build realistic prompt examples and check how they render.

Call graph: calls 1 internal fn (fill_migration_markdown); called by 6 (escape_key_accepts_prompt, prompt_snapshot, prompt_snapshot_gpt5_codex, prompt_snapshot_gpt5_codex_mini, prompt_snapshot_gpt5_family, selecting_use_existing_model_rejects_upgrade); 5 external calls (from, from, new, format!, vec!).

async fn run_model_migration_prompt(
    tui: &mut Tui,
    copy: ModelMigrationCopy,
) -> ModelMigrationOutcome

Purpose: Runs the whole interactive prompt and returns the final outcome: accepted, rejected, or exit. This is the function other code can call when it needs to ask the user about a model migration.

Data flow: It receives the terminal interface and the prepared prompt copy. It enters the alternate screen, creates a ModelMigrationScreen, draws it, then listens for terminal events such as key presses, redraw requests, and resize events. It updates or redraws the screen until the screen says it is done, then returns the recorded outcome.

Call relations: This function wires the prompt together. It uses AltScreenGuard::enter to protect the terminal, creates the screen with ModelMigrationScreen::new, sends key events into ModelMigrationScreen::handle_key, and reads ModelMigrationScreen::outcome at the end.

Call graph: calls 2 internal fn (enter, new); 1 external calls (pin!).

fn new(request_frame: FrameRequester, copy: ModelMigrationCopy) -> Self

Purpose: Creates the in-memory state for a migration prompt screen. It starts with the new-model option highlighted and assumes acceptance unless the user chooses otherwise.

Data flow: It receives a frame requester, which can ask the terminal to redraw, and the prompt copy to display. It stores those, marks the screen as not finished, sets the outcome to accepted, and highlights "Try new model". The initialized screen is returned.

Call relations: The prompt runner calls this before the event loop starts. The tests also use it to create screens that can be rendered or fed key presses without running the full terminal loop.

Call graph: called by 8 (run_model_migration_prompt, escape_key_accepts_prompt, markdown_prompt_keeps_long_url_tail_visible_when_narrow, prompt_snapshot, prompt_snapshot_gpt5_codex, prompt_snapshot_gpt5_codex_mini, prompt_snapshot_gpt5_family, selecting_use_existing_model_rejects_upgrade).

fn finish_with(&mut self, outcome: ModelMigrationOutcome)

Purpose: Marks the prompt as finished with a specific result. It also asks for one more redraw so the terminal can reflect the changed state if needed.

Data flow: It receives the desired outcome. It writes that outcome into the screen, flips the done flag to true, and calls the frame requester to schedule a redraw. It does not return a separate value.

Call relations: The simpler accept, reject, and exit methods all use this shared finishing step, so every ending path updates the state in the same way.

Call graph: calls 1 internal fn (schedule_frame); called by 3 (accept, exit, reject).

fn accept(&mut self)

Purpose: Finishes the prompt as accepted, meaning Codex should proceed with the new model or continue when no opt-out is offered.

Data flow: It reads no external data beyond the screen itself. It sets the final outcome to Accepted through finish_with and marks the screen done. Nothing is returned.

Call relations: It is used when the highlighted option is the new model, when a non-optional prompt is confirmed, and when menu shortcuts choose the new model.

Call graph: calls 1 internal fn (finish_with); called by 3 (confirm_selection, handle_key, handle_menu_key).

fn reject(&mut self)

Purpose: Finishes the prompt as rejected, meaning the user chose to keep the existing model. This is only reachable when opting out is allowed.

Data flow: It changes the screen outcome to Rejected through finish_with and marks the prompt done. It returns nothing.

Call relations: confirm_selection calls this when the existing-model option is highlighted. handle_menu_key also calls it directly for the numeric shortcut that chooses the second option.

Call graph: calls 1 internal fn (finish_with); called by 2 (confirm_selection, handle_menu_key).

fn exit(&mut self)

Purpose: Finishes the prompt as an exit rather than as a model choice. This represents the user pressing a control-key combination such as Ctrl-C or Ctrl-D.

Data flow: It changes the stored outcome to Exit through finish_with and marks the screen done. It returns nothing.

Call relations: handle_key calls this after is_ctrl_exit_combo identifies a control-key exit request.

Call graph: calls 1 internal fn (finish_with); called by 1 (handle_key).

fn confirm_selection(&mut self)

Purpose: Turns the currently highlighted choice into a final answer. If the prompt does not allow opting out, confirmation simply accepts.

Data flow: It reads whether opt-out is allowed and, if so, which menu option is highlighted. Highlighting the new model becomes Accepted; highlighting the existing model becomes Rejected. If opt-out is not allowed, it always accepts.

Call relations: handle_menu_key calls this when the user presses Enter or Escape in the menu flow, so key input becomes a final migration outcome.

Call graph: calls 2 internal fn (accept, reject); called by 1 (handle_menu_key).

fn highlight_option(&mut self, option: MigrationMenuOption)

Purpose: Moves the visible highlight to a given menu option. It only asks for a redraw when the highlighted option actually changes.

Data flow: It receives the option that should be highlighted. If that differs from the current one, it stores the new option and schedules a frame redraw. It returns nothing.

Call relations: handle_menu_key uses this for arrow keys, vim-style movement keys, and numeric shortcuts before accepting or rejecting.

Call graph: calls 1 internal fn (schedule_frame); called by 1 (handle_menu_key).

fn handle_key(&mut self, key_event: KeyEvent)

Purpose: Interprets one keyboard event for the prompt. It decides whether the key should finish the prompt, move through the menu, or be ignored.

Data flow: It receives a key event. Key-release events are ignored, Ctrl-C and Ctrl-D become Exit, opt-out prompts pass the key code to the menu handler, and non-opt-out prompts accept on Escape or Enter. It updates the screen state when a key has meaning.

Call relations: The main prompt loop sends every key event here. This function delegates menu-specific behavior to handle_menu_key and uses is_ctrl_exit_combo to recognize hard-exit shortcuts.

Call graph: calls 4 internal fn (accept, exit, handle_menu_key, is_ctrl_exit_combo); 1 external calls (matches!).

fn is_done(&self) -> bool

Purpose: Reports whether the prompt has reached a final answer. The event loop uses it to know when to stop waiting for input.

Data flow: It reads the screen's done flag and returns that true-or-false value. It does not change anything.

Call relations: run_model_migration_prompt checks this around its event loop so it keeps listening only while the prompt is still active.

fn outcome(&self) -> ModelMigrationOutcome

Purpose: Returns the final outcome stored by the screen. Callers use it after the prompt has finished to know what the user chose.

Data flow: It reads the screen's outcome field and returns a copy of that value. It does not alter the screen.

Call relations: run_model_migration_prompt calls this after the loop ends. Tests also inspect it after simulated key presses.

fn render_ref(&self, area: ratatui::layout::Rect, buf: &mut ratatui::buffer::Buffer)

Purpose: Draws the entire migration prompt into the terminal buffer. This is the screen's main rendering entry point.

Data flow: It receives the area to draw into and the terminal buffer. It clears the area, builds a vertical column of content, chooses markdown rendering or plain heading/content rendering, optionally adds the menu, and writes the column into the buffer.

Call relations: The terminal drawing code calls this whenever the prompt needs to appear or be refreshed. It coordinates heading_line, render_content, render_markdown_content, and render_menu to assemble the visible screen.

Call graph: calls 5 internal fn (heading_line, render_content, render_markdown_content, render_menu, new); 1 external calls (from).

fn handle_menu_key(&mut self, code: KeyCode)

Purpose: Interprets keyboard input when the prompt has a two-choice menu. It supports arrows, j/k movement, number shortcuts, Enter, and Escape.

Data flow: It receives a key code. Up or k highlights the new-model choice; Down or j highlights the existing-model choice; 1 accepts the new model; 2 rejects the migration; Enter or Escape confirms the current highlight. Unknown keys do nothing.

Call relations: handle_key sends key codes here only when the user may opt out. This function then calls highlight_option, accept, reject, or confirm_selection to update the screen.

Call graph: calls 4 internal fn (accept, confirm_selection, highlight_option, reject); called by 1 (handle_key).

fn heading_line(&self) -> Line<'static>

Purpose: Builds the prompt heading as one terminal line. It adds a simple leading marker before the prepared heading text.

Data flow: It reads the heading spans from the prompt copy, prefixes them with "> ", and returns a Line object ready for rendering. It does not change the screen.

Call relations: render_ref calls this when drawing the non-markdown version of the prompt.

Call graph: called by 1 (render_ref); 2 external calls (from, vec!).

fn render_content(&self, column: &mut ColumnRenderable)

Purpose: Adds the prepared plain-text content lines to the render column. It is a small bridge between stored prompt copy and the common line-rendering helper.

Data flow: It reads the content lines from the screen's copy and passes them into render_lines along with the column being built. The column gains those rendered paragraphs.

Call relations: render_ref uses this for normal, non-markdown prompts after drawing the heading.

Call graph: calls 1 internal fn (render_lines); called by 1 (render_ref).

fn render_lines(&self, lines: &[Line<'static>], column: &mut ColumnRenderable)

Purpose: Turns a list of terminal text lines into indented, wrapping paragraphs in the output column. This keeps ordinary prompt text readable at different terminal widths.

Data flow: It receives a slice of lines and a column under construction. For each line, it creates a paragraph that wraps without trimming spaces, adds a left inset, and pushes it into the column. The column is changed; no value is returned.

Call relations: render_content calls this so all plain content lines get the same indentation and wrapping behavior.

Call graph: calls 2 internal fn (tlbr, push); called by 1 (render_content); 1 external calls (new).

fn render_markdown_content(
        &self,
        markdown: &str,
        area_width: u16,
        column: &mut ColumnRenderable,
    )

Purpose: Renders markdown prompt text into terminal lines that fit the current screen width. This supports richer migration messages while still wrapping cleanly.

Data flow: It receives markdown text, the available area width, and the column being built. It subtracts a small left inset to find a usable wrap width, asks the markdown renderer to produce display lines, then inserts each line as an indented paragraph. The column is updated.

Call relations: render_ref calls this instead of the plain heading/content path when ModelMigrationCopy contains markdown. It hands off text wrapping to render_markdown_text_with_width.

Call graph: calls 3 internal fn (render_markdown_text_with_width, tlbr, push); called by 1 (render_ref); 1 external calls (new).

fn render_menu(&self, column: &mut ColumnRenderable)

Purpose: Adds the opt-out menu and its keyboard hints to the prompt. This is the part of the display that lets users choose between the new and existing model.

Data flow: It receives the column being built. It adds spacing, an instruction sentence, one row for each menu option with the current highlight applied, and a final hint line showing which keys move and confirm. The column is updated.

Call relations: render_ref calls this only when the prompt allows opting out. It asks MigrationMenuOption::all for the choices, uses each option's label, and uses selection_option_row to draw consistent selectable rows.

Call graph: calls 4 internal fn (all, tlbr, push, selection_option_row); called by 1 (render_ref); 3 external calls (from, new, vec!).

fn enter(tui: &'a mut Tui) -> Self

Purpose: Switches the terminal into its alternate screen and creates a guard object that will switch it back later. This protects the user's normal scrollback from the large full-screen prompt.

Data flow: It receives a mutable terminal interface. It asks the terminal to enter alternate-screen mode, then stores the terminal reference inside an AltScreenGuard. The guard is returned.

Call relations: run_model_migration_prompt uses this before drawing. The call graph also shows another prompt-like flow, run_session_picker_with_loader, using the same guard pattern.

Call graph: called by 2 (run_model_migration_prompt, run_session_picker_with_loader); 1 external calls (enter_alt_screen).

fn drop(&mut self)

Purpose: Leaves the alternate screen automatically when the guard goes away. This is cleanup code that runs even if the prompt exits early.

Data flow: It uses the terminal reference stored in the guard and asks it to leave alternate-screen mode. It ignores any cleanup error and returns nothing.

Call relations: Rust calls this automatically when AltScreenGuard falls out of scope, so run_model_migration_prompt does not need a separate explicit cleanup step.

Call graph: 1 external calls (leave_alt_screen).

fn is_ctrl_exit_combo(key_event: KeyEvent) -> bool

Purpose: Checks whether a key event is one of the control-key exits for this prompt. In plain terms, it recognizes Ctrl-C and Ctrl-D.

Data flow: It receives a key event, checks that the Control modifier is present, and checks that the key is c or d. It returns true only for those combinations.

Call relations: handle_key uses this before normal menu handling so exit shortcuts take priority over regular prompt choices.

Call graph: called by 1 (handle_key); 1 external calls (matches!).

fn fill_migration_markdown(template: &str, current_model: &str, target_model: &str) -> String

Purpose: Fills a markdown template with the actual old and new model names. This lets server- or config-provided copy contain placeholders instead of hard-coded model names.

Data flow: It receives a template string, the current model name, and the target model name. It replaces {model_from} with the current model and {model_to} with the target model, then returns the completed string.

Call relations: migration_copy_for_models calls this when markdown copy is supplied, before the text is stored in ModelMigrationCopy.

Call graph: called by 1 (migration_copy_for_models).

fn prompt_snapshot()

Purpose: Checks the rendered prompt for a typical opt-out migration message. It helps catch accidental layout or wording changes.

Data flow: The test creates a fake terminal, builds migration copy with custom text and opt-out enabled, renders a ModelMigrationScreen, flushes the terminal, and compares the output to a stored snapshot. The test passes only if the rendering matches the expected screen.

Call relations: It exercises migration_copy_for_models and ModelMigrationScreen::new, then relies on the screen rendering path to produce the snapshot.

Call graph: calls 5 internal fn (with_options, new, migration_copy_for_models, new, test_dummy); 2 external calls (new, assert_snapshot!).

fn prompt_snapshot_gpt5_family()

Purpose: Checks how a non-optional GPT-5 family migration prompt renders when it includes a learn-more link. This protects that specific prompt layout.

Data flow: The test sets up a fake terminal, builds prompt copy with a model link and opt-out disabled, renders the screen, flushes output, and compares it to a stored snapshot. The result is a pass or fail from the snapshot comparison.

Call relations: It uses the same copy builder and screen constructor as production code, then verifies the drawing behavior for the no-opt-out path.

Call graph: calls 5 internal fn (with_options, new, migration_copy_for_models, new, test_dummy); 2 external calls (new, assert_snapshot!).

fn prompt_snapshot_gpt5_codex()

Purpose: Checks the rendered prompt for migrating from a GPT-5 Codex model to a newer Codex max model. It guards the screen layout for this model family.

Data flow: The test creates a fake terminal at a fixed size, builds copy with a link and target description, renders the screen, flushes it, and compares the terminal contents with a stored snapshot.

Call relations: It drives migration_copy_for_models and ModelMigrationScreen::new, then indirectly covers render_ref and its helper rendering functions.

Call graph: calls 5 internal fn (with_options, new, migration_copy_for_models, new, test_dummy); 2 external calls (new, assert_snapshot!).

fn prompt_snapshot_gpt5_codex_mini()

Purpose: Checks the rendered prompt for migrating from one mini Codex model to another. This makes sure the smaller-model wording and layout stay stable.

Data flow: The test builds a fixed-size fake terminal, creates no-opt-out migration copy with a link and description, renders the prompt, flushes the terminal, and compares against a stored snapshot.

Call relations: Like the other snapshot tests, it uses the production copy-building and screen-building functions to verify the final terminal output.

Call graph: calls 5 internal fn (with_options, new, migration_copy_for_models, new, test_dummy); 2 external calls (new, assert_snapshot!).

fn escape_key_accepts_prompt()

Purpose: Verifies the intentional behavior that Escape accepts the prompt rather than counting as an exit. This prevents future changes from accidentally making Escape cancel the migration prompt.

Data flow: The test creates a screen with opt-out enabled, sends it an Escape key event, then checks that the screen is done and that the outcome is Accepted. It does not render the terminal.

Call relations: It calls migration_copy_for_models and ModelMigrationScreen::new to set up realistic state, then exercises ModelMigrationScreen::handle_key and checks is_done and outcome.

Call graph: calls 3 internal fn (new, migration_copy_for_models, test_dummy); 2 external calls (new, assert!).

fn selecting_use_existing_model_rejects_upgrade()

Purpose: Verifies that moving to the second menu option and confirming records a rejection of the upgrade. This protects the opt-out path.

Data flow: The test creates an opt-out screen, sends a Down key to highlight "Use existing model", then sends Enter. It then checks that the screen is done and that the outcome is Rejected.

Call relations: It exercises the key-handling chain from handle_key through handle_menu_key, highlight_option, confirm_selection, and reject.

Call graph: calls 3 internal fn (new, migration_copy_for_models, test_dummy); 2 external calls (new, assert!).

fn markdown_prompt_keeps_long_url_tail_visible_when_narrow()

Purpose: Verifies that markdown rendering does not lose the end of a very long URL in a narrow terminal. This matters because links are often only useful if their final identifying part remains visible.

Data flow: The test creates a screen whose markdown is a long URL, renders it into a narrow fake terminal, converts the terminal contents to text, and asserts that the URL tail appears. The output is a pass or fail from that assertion.

Call relations: It builds a ModelMigrationScreen directly with markdown copy, then exercises the markdown rendering path inside render_ref and render_markdown_content.

Call graph: calls 4 internal fn (with_options, new, new, test_dummy); 3 external calls (new, new, assert!).