App-server and daemon transport bring-up

async fn probe_app_server_version(socket_path: &Path) -> Result<String>

Purpose: Checks an existing app-server socket and asks the server what version it is running. This is useful when callers only need to identify a live server without changing it.

Data flow: It receives a socket path, sends a lightweight probe request through the client code, reads the returned server information, and returns just the app-server version string.

Call relations: This is a small public helper around the lower-level client probe. It does not create a Daemon or start anything; it simply passes the socket path to the client layer and extracts the version.

Call graph: calls 1 internal fn (probe).

fn is_enabled(self) -> bool

Purpose: Turns the remote-control mode value into a simple true or false. Callers use it when they need to store or compare the setting.

Data flow: It receives either Enabled or Disabled and returns true for Enabled and false for Disabled. It changes nothing.

Call relations: The remote-control setting flow calls this inside Daemon::set_remote_control_locked before saving settings or deciding whether a restart is needed.

Call graph: called by 1 (set_remote_control_locked); 1 external calls (matches!).

async fn run(command: LifecycleCommand) -> Result<LifecycleOutput>

Purpose: Public entry for lifecycle commands such as start, restart, stop, and version. It shields callers from setup details.

Data flow: It receives a lifecycle command, checks whether daemon lifecycle support is available on this operating system, creates a Daemon from the environment, and forwards the command to that Daemon. The result is a structured lifecycle report.

Call relations: This is the outer wrapper for Daemon::run. Command-line or API layers can call it without knowing where Codex state files live.

Call graph: calls 2 internal fn (from_environment, ensure_supported_platform).

async fn bootstrap(options: BootstrapOptions) -> Result<BootstrapOutput>

Purpose: Public entry for first-time daemon setup. It prepares the managed app-server and updater using the requested remote-control setting.

Data flow: It receives bootstrap options, checks platform support, builds a Daemon from the environment, and asks it to bootstrap. It returns a report containing paths, versions, backend type, and enabled features.

Call relations: This wraps Daemon::bootstrap so higher layers can request setup without directly constructing daemon paths.

Call graph: calls 2 internal fn (from_environment, ensure_supported_platform).

async fn ensure_remote_control_started() -> Result<RemoteControlStartOutput>

Purpose: Makes sure the daemon is bootstrapped and the app-server is started with remote control enabled. It is used when a caller needs remote-control support but does not care whether setup already happened.

Data flow: It checks platform support, creates the Daemon, and delegates to Daemon::ensure_remote_control_started. The output says whether this was a bootstrap or a normal start.

Call relations: This is the public wrapper around the Daemon method. Daemon::ensure_remote_control_ready builds on it when it also needs to connect remote control.

Call graph: calls 2 internal fn (from_environment, ensure_supported_platform).

async fn ensure_remote_control_ready() -> Result<RemoteControlReadyOutput>

Purpose: Starts or bootstraps the daemon if needed, then makes sure remote control can actually connect. It gives callers one call for the full “make it ready” path.

Data flow: It checks platform support, creates a Daemon, runs the daemon-side remote-control startup flow, then returns both daemon startup information and remote-control connection status.

Call relations: This public wrapper delegates to Daemon::ensure_remote_control_ready, which first calls Daemon::ensure_remote_control_started and then asks the remote-control client to connect.

Call graph: calls 2 internal fn (from_environment, ensure_supported_platform).

async fn enable_remote_control_on_socket(
    socket_path: &Path,
    connect_timeout: Duration,
    connect_retry_delay: Duration,
) -> Result<RemoteControlReadyStatus>

Purpose: Enables remote control on a specific app-server socket, retrying for a limited time. This is useful when the caller already knows the socket path and does not need full daemon setup.

Data flow: It receives a socket path, total connection timeout, and delay between retries. After checking platform support, it asks the remote-control client to keep trying until it connects or times out, and returns the final ready status.

Call relations: Unlike the Daemon-based helpers, this function works directly with a supplied socket. It hands the actual retry behavior to remote_control_client::enable_remote_control_with_connect_retry.

Call graph: calls 2 internal fn (ensure_supported_platform, enable_remote_control_with_connect_retry).

async fn set_remote_control(mode: RemoteControlMode) -> Result<RemoteControlOutput>

Purpose: Public entry for turning daemon-managed remote control on or off. It updates saved settings and restarts the managed server if the change must take effect immediately.

Data flow: It receives the desired mode, checks platform support, creates a Daemon from the environment, and delegates to the Daemon. The result reports the new state and any running server version.

Call relations: This is the public wrapper around Daemon::set_remote_control. The detailed work happens under the daemon operation lock.

Call graph: calls 2 internal fn (from_environment, ensure_supported_platform).

async fn run_pid_update_loop() -> Result<()>

Purpose: Starts the daemon's updater loop. The updater is the background task that keeps the managed app-server refreshed.

Data flow: It checks that the platform is supported and then runs the update loop. It returns success when the loop exits normally or an error if startup or loop execution fails.

Call relations: This is the public entry into the update_loop module. Bootstrap starts a separate updater backend that ultimately uses this path.

Call graph: calls 2 internal fn (ensure_supported_platform, run).

fn ensure_supported_platform() -> Result<()>

Purpose: Stops daemon lifecycle code from running on unsupported operating systems. In this file, lifecycle support is Unix-only.

Data flow: It reads no input. On Unix it returns success; on non-Unix platforms it returns an explanatory error.

Call relations: Every public lifecycle or remote-control entry point calls this first, so unsupported systems fail early before touching files or sockets.

Call graph: called by 7 (bootstrap, enable_remote_control_on_socket, ensure_remote_control_ready, ensure_remote_control_started, run, run_pid_update_loop, set_remote_control); 1 external calls (anyhow!).

fn from_environment() -> Result<Self>

Purpose: Builds a Daemon object using the current Codex home directory. This gathers all the file paths the daemon needs into one place.

Data flow: It finds CODEX_HOME, derives the app-server socket path, state directory, PID files, lock file, settings file, and managed Codex binary path, then returns a Daemon containing those paths.

Call relations: Public wrapper functions call this before delegating to Daemon methods. The update code also uses it when it needs the same environment-based daemon layout.

Call graph: calls 1 internal fn (managed_codex_bin); called by 6 (bootstrap, ensure_remote_control_ready, ensure_remote_control_started, run, set_remote_control, update_once); 2 external calls (app_server_control_socket_path, find_codex_home).

async fn run(&self, command: LifecycleCommand) -> Result<LifecycleOutput>

Purpose: Dispatches a lifecycle command to the matching daemon action. It also ensures start, restart, and stop do not overlap with another operation.

Data flow: It receives a command. For start, restart, and stop it acquires the operation lock, then calls the matching method. For version it calls version directly. It returns the lifecycle output from that method.

Call relations: The public run function calls this. It is the switchboard that routes user commands to Daemon::start, Daemon::restart, Daemon::stop, or Daemon::version.

Call graph: calls 5 internal fn (acquire_operation_lock, restart, start, stop, version).

async fn start(&self) -> Result<LifecycleOutput>

Purpose: Starts the managed app-server if it is not already running. It avoids duplicate launches by first checking both the socket and the daemon-owned backend.

Data flow: It loads settings, probes the socket, checks for an existing daemon-owned process, verifies the managed Codex binary exists, starts the backend if needed, waits until the socket answers, and returns a lifecycle report.

Call relations: Daemon::run calls this for Start, and Daemon::ensure_remote_control_started calls it after enabling remote control. It relies on client probing, backend startup, and output formatting helpers.

Call graph: calls 8 internal fn (ensure_managed_codex_bin, load_settings, output, running_backend, running_backend_instance, start_managed_backend, wait_until_ready, probe); called by 2 (ensure_remote_control_started, run).

async fn restart(&self) -> Result<LifecycleOutput>

Purpose: Stops the daemon-owned app-server and launches a fresh one. It refuses to restart an app-server that exists but is not owned by this daemon.

Data flow: It loads settings, probes the socket, checks ownership through the backend, verifies the managed binary, stops any daemon-owned process, starts a new managed backend, waits for readiness, and returns a Restarted report.

Call relations: Daemon::run calls this for Restart. It uses the same backend and readiness helpers as start, but always replaces the daemon-owned process.

Call graph: calls 8 internal fn (ensure_managed_codex_bin, load_settings, output, running_backend, running_backend_instance, start_managed_backend, wait_until_ready, probe); called by 1 (run); 1 external calls (anyhow!).

async fn try_restart_if_running(
        &self,
        mode: RestartMode,
        updater_refresh_mode: UpdaterRefreshMode,
        managed_codex_bin: &Path,
    ) -> Result<RestartIfRunningOutcome>

Purpose: Used by the updater to restart the app-server only when it is safe and appropriate. It can skip work if another operation is busy, the server is not ready, or the running version is already current.

Data flow: It opens and tries to lock the operation file without waiting. If locked, it loads settings, checks for a daemon-owned backend, probes the server, optionally compares versions, restarts with the supplied managed binary when needed, and may re-execute the updater after a successful restart.

Call relations: This method is mainly for the update path. It calls restart_decision to decide what to do and should_reexec_updater to decide whether the updater process should replace itself.

Call graph: calls 11 internal fn (load_settings, open_operation_lock_file, running_backend_instance, start_managed_backend_with_bin, wait_until_ready, probe, managed_codex_version, restart_decision, should_reexec_updater, try_lock_file (+1 more)); 1 external calls (anyhow!).

async fn stop(&self) -> Result<LifecycleOutput>

Purpose: Stops the daemon-owned app-server if it is running. It avoids killing an app-server that the daemon did not start.

Data flow: It loads settings, checks for a daemon-owned backend, stops it if found, and returns Stopped. If no backend is found but the socket answers, it returns an error because another app-server is running. Otherwise it reports NotRunning.

Call relations: Daemon::run calls this for Stop. It uses backend ownership checks and socket probing to distinguish safe stops from unsafe interference.

Call graph: calls 4 internal fn (load_settings, output, running_backend_instance, probe); called by 1 (run); 1 external calls (anyhow!).

async fn version(&self) -> Result<LifecycleOutput>

Purpose: Reports the version of the currently reachable app-server. It also says whether the daemon appears to own the running backend.

Data flow: It loads settings, probes the socket to get the app-server version, checks the daemon backend state, and returns a Running lifecycle output with version information.

Call relations: Daemon::run calls this for Version. It shares the output formatting path used by start, stop, and restart.

Call graph: calls 4 internal fn (load_settings, output, running_backend, probe); called by 1 (run).

async fn wait_until_ready(&self) -> Result<client::ProbeInfo>

Purpose: Waits for the app-server socket to begin answering after a start or restart. This turns a process launch into a usable service.

Data flow: It repeatedly probes the socket until it succeeds or a timeout is reached. On success it returns probe information; on timeout it adds helpful diagnostic context and returns the last error.

Call relations: Start, restart, bootstrap, remote-control changes, and updater restarts call this after launching the backend. If probing fails too long, it asks app_server_not_ready_context for a better error message.

Call graph: calls 2 internal fn (app_server_not_ready_context, probe); called by 5 (bootstrap_locked, restart, set_remote_control_locked, start, try_restart_if_running); 2 external calls (now, sleep).

async fn app_server_not_ready_context(&self) -> String

Purpose: Builds a useful error message when the app-server was launched but never became reachable. It helps users understand what binary was used and what the server printed.

Data flow: It starts with the socket path, appends managed Codex binary details, then appends the tail of the stderr log if available. It returns the combined text.

Call relations: Daemon::wait_until_ready calls this only on timeout. It combines local daemon context with backend log context.

Call graph: calls 2 internal fn (append_daemon_app_server_context, append_stderr_log_tail_context); called by 1 (wait_until_ready); 1 external calls (format!).

async fn append_daemon_app_server_context(&self, context: &mut String)

Purpose: Adds the managed app-server path and best-known version to an error message. This makes failures easier to diagnose.

Data flow: It receives a mutable text buffer, tries to read the managed Codex version, falls back to unknown, and appends path and version lines to the buffer.

Call relations: Daemon::app_server_not_ready_context calls this before appending stderr log output, so the final message first identifies what binary the daemon tried to run.

Call graph: calls 1 internal fn (managed_codex_version_best_effort); called by 1 (app_server_not_ready_context); 1 external calls (format!).

async fn bootstrap(&self, options: BootstrapOptions) -> Result<BootstrapOutput>

Purpose: Runs bootstrap setup while holding the operation lock. Bootstrap prepares both the app-server backend and the updater backend.

Data flow: It acquires the operation lock, then passes the requested options to bootstrap_locked. It returns the bootstrap report from that locked operation.

Call relations: The public bootstrap wrapper calls this. It exists to separate locking from the detailed bootstrap steps.

Call graph: calls 2 internal fn (acquire_operation_lock, bootstrap_locked).

async fn ensure_remote_control_started(&self) -> Result<RemoteControlStartOutput>

Purpose: Makes sure remote control is enabled and the managed app-server is running. It bootstraps if the daemon has not been fully set up yet.

Data flow: It acquires the operation lock, loads settings, checks whether the updater backend indicates bootstrap has happened, then either enables remote control and starts the server or bootstraps with remote control enabled. It returns which path was used.

Call relations: Daemon::ensure_remote_control_ready calls this first. The public ensure_remote_control_started wrapper also reaches this through Daemon construction.

Call graph: calls 6 internal fn (acquire_operation_lock, bootstrap_locked, is_bootstrapped, load_settings, set_remote_control_locked, start); called by 1 (ensure_remote_control_ready); 2 external calls (Bootstrap, Start).

async fn ensure_remote_control_ready(&self) -> Result<RemoteControlReadyOutput>

Purpose: Completes the full remote-control readiness path: daemon started, app-server running, and remote control connected.

Data flow: It calls ensure_remote_control_started, then asks the remote-control client to enable or connect through the daemon socket. It returns both daemon startup output and remote-control connection status.

Call relations: The public ensure_remote_control_ready wrapper delegates here. This method ties together daemon lifecycle work and remote-control client work.

Call graph: calls 2 internal fn (ensure_remote_control_started, enable_remote_control).

async fn set_remote_control(&self, mode: RemoteControlMode) -> Result<RemoteControlOutput>

Purpose: Changes the remote-control setting while preventing concurrent daemon operations. It is the locked wrapper around the detailed setting logic.

Data flow: It receives the desired mode, acquires the operation lock, calls set_remote_control_locked, and returns the resulting status report.

Call relations: The public set_remote_control wrapper calls this. The split keeps locking policy separate from the setting and restart decisions.

Call graph: calls 2 internal fn (acquire_operation_lock, set_remote_control_locked).

async fn set_remote_control_locked(
        &self,
        mode: RemoteControlMode,
    ) -> Result<RemoteControlOutput>

Purpose: Actually turns remote control on or off in settings and, if the managed server is running, makes that change active. This may involve restarting the app-server.

Data flow: It loads previous settings, converts the requested mode to true or false, checks whether the daemon owns any running backend, rejects unmanaged running servers, saves changed settings, restarts the managed backend if needed, and returns a remote-control output report.

Call relations: Daemon::set_remote_control and Daemon::ensure_remote_control_started call this while holding the operation lock. It uses status helpers to report whether the setting changed or was already in that state.

Call graph: calls 12 internal fn (ensure_managed_codex_bin, load_settings, remote_control_output, running_backend_instance, start_managed_backend, wait_until_ready, is_enabled, already_remote_control_status, probe, disable_remote_control (+2 more)); called by 2 (ensure_remote_control_started, set_remote_control); 1 external calls (anyhow!).

async fn bootstrap_locked(&self, options: BootstrapOptions) -> Result<BootstrapOutput>

Purpose: Performs the real bootstrap work after locking has already been handled. It writes settings, starts the app-server, and starts the updater.

Data flow: It verifies the managed Codex binary exists, creates settings from the options, refuses to take over an unmanaged running server, saves settings, stops any old daemon-owned app-server, starts the app-server backend, restarts the updater backend, waits for readiness, and returns a bootstrap report.

Call relations: Daemon::bootstrap and Daemon::ensure_remote_control_started call this. It coordinates backend creation, settings persistence, updater startup, and readiness probing.

Call graph: calls 9 internal fn (backend_paths, ensure_managed_codex_bin, managed_codex_version_best_effort, running_backend, running_backend_instance, wait_until_ready, pid_backend, pid_update_loop_backend, probe); called by 2 (bootstrap, ensure_remote_control_started); 3 external calls (clone, anyhow!, env!).

async fn running_backend(&self, settings: &DaemonSettings) -> Result<Option<BackendKind>>

Purpose: Reports what kind of daemon-owned backend is currently running, without exposing the backend object itself. At present, that backend kind is PID-file based.

Data flow: It receives settings, asks running_backend_instance whether a backend is active, and converts an active instance into BackendKind::Pid. It returns either Some(Pid) or None.

Call relations: Start, restart, version, and bootstrap use this when they only need a user-facing backend label rather than an object they can stop or start.

Call graph: calls 1 internal fn (running_backend_instance); called by 4 (bootstrap_locked, restart, start, version).

async fn running_backend_instance(
        &self,
        settings: &DaemonSettings,
    ) -> Result<Option<backend::PidBackend>>

Purpose: Checks whether the daemon-owned app-server backend is starting or running. It returns the backend object when there is one to act on.

Data flow: It builds backend paths from settings, creates a PID backend, asks whether it is starting or running, and returns the backend object if active.

Call relations: Many lifecycle paths use this before stopping, restarting, or deciding ownership. It is the main guard against interfering with unmanaged app-server processes.

Call graph: calls 2 internal fn (backend_paths, pid_backend); called by 7 (bootstrap_locked, restart, running_backend, set_remote_control_locked, start, stop, try_restart_if_running).

async fn start_managed_backend(&self, settings: &DaemonSettings) -> Result<Option<u32>>

Purpose: Starts the app-server using the daemon's configured managed Codex binary. It is the normal launch helper.

Data flow: It receives settings, forwards them with the daemon's managed binary path to start_managed_backend_with_bin, and returns the launched process ID when available.

Call relations: Start, restart, and remote-control setting changes call this. The updater-specific path can bypass it by calling start_managed_backend_with_bin with a chosen binary.

Call graph: calls 1 internal fn (start_managed_backend_with_bin); called by 3 (restart, set_remote_control_locked, start).

async fn start_managed_backend_with_bin(
        &self,
        settings: &DaemonSettings,
        managed_codex_bin: &Path,
    ) -> Result<Option<u32>>

Purpose: Starts the app-server using a specific Codex binary path. This lets the updater launch a newly installed managed binary.

Data flow: It receives settings and a binary path, builds backend paths using that binary, creates the PID backend, starts it, and returns an optional process ID.

Call relations: start_managed_backend calls this for normal starts. try_restart_if_running calls it directly when the updater wants to restart with a supplied managed binary.

Call graph: calls 2 internal fn (backend_paths_with_bin, pid_backend); called by 2 (start_managed_backend, try_restart_if_running).

async fn is_bootstrapped(&self, settings: &DaemonSettings) -> Result<bool>

Purpose: Checks whether daemon bootstrap appears to have happened by looking for the updater backend. The updater is treated as the sign that full daemon setup is active.

Data flow: It receives settings, builds updater backend paths, asks whether that updater is starting or running, and returns true or false.

Call relations: Daemon::ensure_remote_control_started uses this to choose between a simple start path and a full bootstrap path.

Call graph: calls 2 internal fn (backend_paths, pid_update_loop_backend); called by 1 (ensure_remote_control_started).

fn ensure_managed_codex_bin(&self) -> Result<()>

Purpose: Verifies that the managed standalone Codex binary exists before the daemon tries to launch it. Without this check, later startup errors would be harder to understand.

Data flow: It checks whether the configured managed binary path is a file. If it exists, it returns success; if not, it returns an error explaining how to install the standalone managed Codex.

Call relations: Start, restart, bootstrap, and remote-control restart paths call this before launching a managed app-server.

Call graph: called by 4 (bootstrap_locked, restart, set_remote_control_locked, start); 3 external calls (display, is_file, anyhow!).

async fn managed_codex_version_best_effort(&self) -> Option<String>

Purpose: Tries to read the version of the managed Codex binary without making version lookup failures fatal. This is mainly for reporting and diagnostics.

Data flow: It asks the managed-install code for the binary version. On success it returns the version string; on failure it returns None.

Call relations: Output formatting, bootstrap reporting, and readiness error context call this to include version information when available.

Call graph: calls 1 internal fn (managed_codex_version); called by 3 (append_daemon_app_server_context, bootstrap_locked, output).

fn backend_paths(&self, settings: &DaemonSettings) -> BackendPaths

Purpose: Builds the set of paths and flags needed to create backend objects using the daemon's normal managed Codex binary.

Data flow: It receives settings and forwards them, along with the daemon's managed binary path, to backend_paths_with_bin. The result is a BackendPaths value.

Call relations: Backend checks, bootstrap, and updater checks use this whenever they need backend configuration for the standard managed binary.

Call graph: calls 1 internal fn (backend_paths_with_bin); called by 3 (bootstrap_locked, is_bootstrapped, running_backend_instance).

fn backend_paths_with_bin(
        &self,
        settings: &DaemonSettings,
        managed_codex_bin: &Path,
    ) -> BackendPaths

Purpose: Assembles the exact backend configuration for a given Codex binary. This is the shared recipe for app-server and updater backend objects.

Data flow: It receives settings and a binary path, copies the binary path and PID file paths, includes the remote-control flag, and returns a BackendPaths struct.

Call relations: backend_paths calls this for normal use. start_managed_backend_with_bin calls it when launching with a specific binary path.

Call graph: called by 2 (backend_paths, start_managed_backend_with_bin); 2 external calls (to_path_buf, clone).

async fn load_settings(&self) -> Result<DaemonSettings>

Purpose: Reads daemon settings from disk. These settings currently include whether remote control should be enabled.

Data flow: It uses the daemon's settings file path, asks DaemonSettings to load it, and returns the settings or an error.

Call relations: Lifecycle, remote-control, and updater restart paths call this before deciding how to start or inspect the backend.

Call graph: calls 1 internal fn (load); called by 7 (ensure_remote_control_started, restart, set_remote_control_locked, start, stop, try_restart_if_running, version).

async fn acquire_operation_lock(&self) -> Result<tokio::fs::File>

Purpose: Waits for exclusive permission to perform a daemon operation. This prevents races like one command stopping the server while another starts it.

Data flow: It opens the lock file, repeatedly tries to lock it until success or a timeout, sleeps briefly between attempts, and returns the open locked file. Keeping the file alive keeps the lock held.

Call relations: Daemon::run, bootstrap, ensure_remote_control_started, and set_remote_control use this before changing daemon state. It depends on open_operation_lock_file and try_lock_file.

Call graph: calls 2 internal fn (open_operation_lock_file, try_lock_file); called by 4 (bootstrap, ensure_remote_control_started, run, set_remote_control); 3 external calls (anyhow!, now, sleep).

async fn open_operation_lock_file(&self) -> Result<tokio::fs::File>

Purpose: Creates or opens the file used as the daemon operation lock. The lock file is the shared object that operating-system locking works on.

Data flow: It ensures the parent state directory exists, opens the lock file for writing, and returns the file handle. If directory creation or opening fails, it adds the path to the error.

Call relations: acquire_operation_lock uses this before waiting for the lock. try_restart_if_running also uses it when the updater wants a non-waiting lock attempt.

Call graph: called by 2 (acquire_operation_lock, try_restart_if_running); 3 external calls (parent, new, create_dir_all).

async fn output(
        &self,
        status: LifecycleStatus,
        backend: Option<BackendKind>,
        pid: Option<u32>,
        app_server_version: Option<String>,
    ) -> LifecycleOutput

Purpose: Builds a standard lifecycle response for start, restart, stop, and version commands. It keeps response fields consistent across those commands.

Data flow: It receives status, backend, optional process ID, and optional app-server version. It adds managed binary path, best-effort managed binary version, socket path, and CLI version, then returns a LifecycleOutput.

Call relations: Start, restart, stop, and version call this after their work is done. It centralizes the user-facing lifecycle report shape.

Call graph: calls 1 internal fn (managed_codex_version_best_effort); called by 4 (restart, start, stop, version); 2 external calls (clone, env!).

fn remote_control_output(
        &self,
        status: RemoteControlStatus,
        backend: Option<BackendKind>,
        remote_control_enabled: bool,
        app_server_version: Option<String>,

Purpose: Builds the standard response for remote-control setting changes. It reports both the saved setting and any live app-server version.

Data flow: It receives remote-control status, optional backend, enabled flag, and optional app-server version. It adds socket path and CLI version, then returns a RemoteControlOutput.

Call relations: set_remote_control_locked calls this for both changed and already-unchanged cases.

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

fn remote_control_status(mode: RemoteControlMode) -> RemoteControlStatus

Purpose: Converts a requested remote-control mode into the status used when the setting actually changed. It makes reporting consistent.

Data flow: It receives Enabled or Disabled and returns the matching Enabled or Disabled status value.

Call relations: set_remote_control_locked calls this after saving a changed setting and applying any needed restart.

Call graph: called by 1 (set_remote_control_locked).

fn already_remote_control_status(mode: RemoteControlMode) -> RemoteControlStatus

Purpose: Converts a requested remote-control mode into the status used when the daemon was already in that mode. This lets callers distinguish no-op changes from real changes.

Data flow: It receives Enabled or Disabled and returns AlreadyEnabled or AlreadyDisabled.

Call relations: set_remote_control_locked calls this when the saved setting already matches the requested mode.

Call graph: called by 1 (set_remote_control_locked).

fn restart_decision(
    mode: RestartMode,
    info: Option<&client::ProbeInfo>,
    managed_version: Option<&str>,
) -> RestartDecision

Purpose: Decides whether the updater should restart the app-server. It can avoid a restart when the running app-server already matches the managed binary version.

Data flow: It receives a restart mode, optional probe information from the running server, and optional managed binary version. It returns NotReady, AlreadyCurrent, or Restart.

Call relations: try_restart_if_running calls this after probing the server and reading the managed version. The decision controls whether that method skips, reports not ready, or restarts.

Call graph: called by 1 (try_restart_if_running).

fn should_reexec_updater(
    updater_refresh_mode: UpdaterRefreshMode,
    outcome: RestartIfRunningOutcome,
) -> bool

Purpose: Decides whether the updater process should replace itself after restarting the app-server. This only happens after a validated restart with a changed managed binary.

Data flow: It receives an updater refresh mode and the restart outcome. It returns true only when refresh mode requests re-execution and the outcome was Restarted.

Call relations: try_restart_if_running calls this near the end. If it returns true, the update loop is asked to re-execute using the managed binary.

Call graph: called by 1 (try_restart_if_running).

fn try_lock_file(_file: &tokio::fs::File) -> Result<bool>

Purpose: Attempts to take an exclusive file lock without waiting. A file lock is an operating-system lock that lets processes agree who may touch shared state.

Data flow: It receives an open file. On Unix it calls the system flock operation; it returns true if the lock was taken, false if another process already holds it, or an error for unexpected failures. On non-Unix in this code path, it succeeds.

Call relations: acquire_operation_lock uses this in a retry loop. try_restart_if_running uses it once so the updater can back off instead of blocking.

Call graph: called by 2 (acquire_operation_lock, try_restart_if_running); 3 external calls (as_raw_fd, last_os_error, flock).

fn remote_control_status_uses_camel_case_json()

Purpose: Checks that remote-control status values serialize to the JSON spelling expected by callers. This protects the public API shape.

Data flow: It serializes AlreadyEnabled to JSON and compares the result with the expected string alreadyEnabled.

Call relations: This test covers the serde naming behavior used by RemoteControlOutput and related API responses.

Call graph: 1 external calls (assert_eq!).

fn updater_reexec_waits_for_validated_restart()

Purpose: Verifies that updater re-execution happens only after a successful restart. This avoids replacing the updater after skipped or failed restart attempts.

Data flow: It feeds several restart outcomes into should_reexec_updater with refresh mode enabled and checks that only Restarted returns true.

Call relations: This test protects the decision used by Daemon::try_restart_if_running after updater-driven restarts.

Call graph: 1 external calls (assert_eq!).

fn unchanged_updater_never_reexecs()

Purpose: Verifies that the updater does not re-execute when refresh mode is disabled. This prevents unnecessary updater replacement.

Data flow: It feeds several restart outcomes into should_reexec_updater with refresh mode None and checks that every result is false.

Call relations: This test covers the no-refresh branch used by Daemon::try_restart_if_running.

Call graph: 1 external calls (assert_eq!).

fn restart_decision_preserves_forced_refreshes()

Purpose: Checks the restart decision rules for version-based and forced restarts. It ensures forced refreshes still restart even when versions match.

Data flow: It creates sample probe information, calls restart_decision with different modes and available data, and compares the decisions with expected results.

Call relations: This test protects the logic that Daemon::try_restart_if_running uses before stopping and starting the backend.

Call graph: 1 external calls (assert_eq!).

fn remote_control_start_output_serializes_inner_output_without_tag()

Purpose: Checks that remote-control startup output serializes exactly like the inner lifecycle or bootstrap output, without an extra wrapper tag. This keeps the API response simple for clients.

Data flow: It builds sample LifecycleOutput and BootstrapOutput values, wraps each in RemoteControlStartOutput, serializes them, and verifies the wrapped JSON matches the inner JSON.

Call relations: This test protects the untagged serialization behavior used by ensure_remote_control_started and ensure_remote_control_ready outputs.

Call graph: 3 external calls (Bootstrap, Start, assert_eq!).

async fn not_ready_context_reports_daemon_app_server_before_stderr()

Purpose: Checks the order and content of the error context shown when the app-server does not become ready. The message should identify the daemon's binary before showing stderr output.

Data flow: It creates a temporary daemon layout, writes a fake stderr log, asks for the not-ready context, and compares it with the expected text.

Call relations: This test covers Daemon::app_server_not_ready_context and indirectly Daemon::append_daemon_app_server_context, which are used by wait_until_ready on timeout.

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

fn pid_backend(paths: BackendPaths) -> PidBackend

Purpose: Creates the normal PID-based backend for the managed app-server. Callers use it when they need an object that knows how to work with the app-server process recorded in the main PID file.

Data flow: It receives a BackendPaths bundle containing the Codex binary path, the main PID file path, the update-loop PID file path, and a remote-control flag. It takes the binary path, main PID file path, and remote-control flag, passes them into PidBackend::new, and returns the resulting backend object. The update-loop PID file is not used here because this function is only for the main backend.

Call relations: During bootstrap, backend lookup, or starting a managed backend with a chosen binary, callers ask pid_backend to build the main backend for them. This function then hands the real construction work to new, so the rest of the daemon does not need to know the exact constructor details.

Call graph: calls 1 internal fn (new); called by 3 (bootstrap_locked, running_backend_instance, start_managed_backend_with_bin).

fn pid_update_loop_backend(paths: BackendPaths) -> PidBackend

Purpose: Creates the PID-based backend used for the update loop, which is tracked separately from the main app-server. This lets the daemon check or start the updater without confusing it with the main server process.

Data flow: It receives the same BackendPaths bundle as the main backend builder. It uses the Codex binary path and the update-loop PID file path, passes them into PidBackend::new_update_loop, and returns the resulting backend object.

Call relations: Bootstrap and bootstrapping checks call this when they need to reason about the update-loop process. The function delegates to new_update_loop, keeping the caller focused on the larger startup question instead of the details of constructing that backend.

Call graph: calls 1 internal fn (new_update_loop); called by 2 (bootstrap_locked, is_bootstrapped).

async fn append_stderr_log_tail_context(pid_file: &Path, context: &mut String)

Purpose: Adds recent stderr log output from the managed app-server to an existing error message, when that output is available. This helps a person understand why the server was not ready, instead of only seeing a vague readiness failure.

Data flow: It receives a path to the PID file and a mutable text string used as context. It asks read_stderr_log_tail to find and read the recent stderr log connected to that PID file. If a log tail is found, it appends that text to the context string. If no log is found, it leaves the context unchanged. If reading fails, it appends a short message describing that failure.

Call relations: When app_server_not_ready_context is building an explanation for a readiness problem, it calls this helper to enrich the message. This function relies on read_stderr_log_tail for the actual log reading and uses formatting only to turn a read error into clear text for the final context.

Call graph: calls 1 internal fn (read_stderr_log_tail); called by 1 (app_server_not_ready_context); 1 external calls (format!).

fn append_to_context(&self, context: &mut String)

Purpose: Adds the saved tail of the managed server’s stderr log to an existing error message. This makes failures easier to diagnose because the caller sees the last lines the background process wrote before or during the problem.

Data flow: It receives a mutable text buffer and reads the log path and log contents stored in the PidLogTail. It appends a heading with the file path, then appends each log line indented underneath. It does not return a new value; it changes the provided text buffer in place.

Call relations: When another part of the daemon wants to enrich an error report, it can first fetch a PidLogTail and then call this method to paste the log into the report. This method is the final formatting step after the log tail has already been read.

Call graph: 1 external calls (format!).

fn new(codex_bin: PathBuf, pid_file: PathBuf, remote_control_enabled: bool) -> Self

Purpose: Creates a PID-based backend for the normal app server. It stores where the Codex binary is, where the PID file should live, and whether remote control should be enabled when the server starts.

Data flow: It takes the path to the executable, the PID file path, and a true-or-false remote-control setting. It derives a matching lock-file path from the PID file and returns a PidBackend configured for an app-server command.

Call relations: Higher-level setup code and tests call this when they need a backend for the regular app server. Later, methods such as start, stop, and is_starting_or_running use the paths and command choice saved here.

Call graph: called by 8 (pid_backend, app_server_disabled_remote_control_uses_compatible_args_and_runtime_env, app_server_remote_control_uses_runtime_flag, locked_empty_pid_file_is_treated_as_active_reservation, stale_record_cleanup_preserves_replacement_record, start_retries_stale_empty_pid_file_under_its_own_lock, stop_waits_for_live_reservation_to_resolve, unlocked_empty_pid_file_is_treated_as_stale_reservation); 1 external calls (with_extension).

fn new_update_loop(codex_bin: PathBuf, pid_file: PathBuf) -> Self

Purpose: Creates a PID-based backend for the updater loop instead of the normal app server. The updater is started and stopped with slightly different command and kill behavior.

Data flow: It takes the executable path and PID file path, derives the matching lock-file path, and returns a PidBackend marked as an update-loop command. No files are touched yet; it only prepares the settings.

Call relations: Code that supervises the update loop calls this constructor. The rest of the backend methods then reuse the same PID-file machinery but choose updater-specific command arguments and forced shutdown behavior.

Call graph: called by 1 (pid_update_loop_backend); 1 external calls (with_extension).

async fn is_starting_or_running(&self) -> Result<bool>

Purpose: Answers the practical question: “Is this managed process either already running or currently being started?” It also cleans up a stale PID record if it points to a process that is no longer really the same process.

Data flow: It reads the PID-file state. If there is no file, it returns false. If a start reservation is active, it returns true. If there is a running record, it checks whether that record still matches a live process; stale records are refreshed under the lock before deciding.

Call relations: Status-checking code calls this before deciding whether to start another server or report that one exists. It relies on read_pid_file_state for the file view, record_is_active for the process check, and refresh_after_stale_record to safely remove outdated records.

Call graph: calls 3 internal fn (read_pid_file_state, record_is_active, refresh_after_stale_record).

async fn start(&self) -> Result<Option<u32>>

Purpose: Starts the managed process if it is not already running. On Unix, it launches a detached child process and publishes a PID record; on unsupported platforms it reports that this startup style is not available.

Data flow: It uses the backend’s executable path, PID file, lock file, command kind, and remote-control setting. It creates the PID directory, obtains the reservation lock, reserves the PID file, opens a stderr log, builds the command, launches the child, reads the child’s start time, writes a JSON PID record through a temporary file, and returns the new process ID. If another valid process is already recorded, it returns no PID instead of starting a duplicate. On failure, it removes reservations and may terminate the child it just spawned.

Call relations: Startup orchestration calls this when it wants the daemon running. Inside the flow it coordinates many helpers: locking, stale-record checks, command argument selection, stderr-log creation, process start-time reading, and cleanup termination if a later step fails.

Call graph: calls 8 internal fn (acquire_reservation_lock, command_args, command_env, open_stderr_log, read_pid_file_state_with_lock_held, record_is_active, terminate_process, read_process_start_time); 15 external calls (parent, with_extension, from, null, bail!, new, format!, new, create_dir_all, remove_file (+5 more)).

async fn stop(&self) -> Result<()>

Purpose: Stops the managed process, waiting safely if startup is still in progress. It first asks the process to exit normally, then forcefully kills it if it stays alive too long.

Data flow: It reads or waits for a PID record, verifies that the record still matches the live process, sends a normal termination signal, and then repeatedly checks whether the process has gone away. After a grace period it escalates to a forceful kill. It returns success once the PID file is gone or stale state is cleared, and returns an error if the process still appears active after the timeout.

Call relations: Shutdown code calls this when the daemon should stop. It depends on wait_for_pid_start so it does not race with startup, uses record_is_active and refresh_after_stale_record to avoid trusting stale files, and hands off to terminate_process or force_terminate_process for the actual operating-system signal.

Call graph: calls 5 internal fn (force_terminate_process, record_is_active, refresh_after_stale_record, terminate_process, wait_for_pid_start); 3 external calls (bail!, now, sleep).

async fn wait_for_pid_start(&self) -> Result<Option<PidRecord>>

Purpose: Waits briefly for an in-progress PID reservation to turn into a real PID record. This avoids stopping or inspecting the server while another task is halfway through starting it.

Data flow: It repeatedly reads the PID-file state until it sees no file, a running record, or a starting reservation that lasts too long. Missing becomes None, a running record becomes Some(record), and a stuck reservation becomes an error.

Call relations: stop calls this at the beginning of each shutdown attempt. It uses read_pid_file_state to watch the reservation and sleeps between checks so it does not spin wastefully.

Call graph: calls 1 internal fn (read_pid_file_state); called by 1 (stop); 3 external calls (bail!, now, sleep).

async fn read_pid_file_state(&self) -> Result<PidFileState>

Purpose: Interprets the PID file and lock file as one of three states: missing, starting, or running. This is the main reader that understands the on-disk protocol.

Data flow: It tries to read the PID file. If the file is missing, it checks whether the lock file is currently held and returns either Starting or Missing. If the file is empty, it inspects whether that empty file is an active reservation, a stale leftover, or a file that was filled meanwhile. If the file has contents, it parses the JSON PID record and returns Running.

Call relations: Status checks and stop-waiting code call this to get a safe view of the process state. It delegates the tricky empty-file cases to reservation_lock_is_active and inspect_empty_pid_reservation.

Call graph: calls 2 internal fn (inspect_empty_pid_reservation, reservation_lock_is_active); called by 2 (is_starting_or_running, wait_for_pid_start); 3 external calls (Running, read_to_string, from_str).

async fn read_pid_file_state_with_lock_held(&self) -> Result<PidFileState>

Purpose: Reads the PID file when the caller already owns the reservation lock. Because the lock is held, an empty PID file cannot be a live reservation by another task, so it can be treated as stale.

Data flow: It reads the PID file. Missing means Missing. Empty contents are removed and treated as Missing. Non-empty contents are parsed as a PID record and returned as Running.

Call relations: start uses this after it wins the lock and discovers a PID file already exists. refresh_after_stale_record also uses it while holding the lock so it can safely decide whether to remove an outdated record.

Call graph: called by 2 (refresh_after_stale_record, start); 4 external calls (Running, read_to_string, remove_file, from_str).

async fn refresh_after_stale_record(&self, expected: &PidRecord) -> Result<PidFileState>

Purpose: Safely removes a PID file only if it still contains the stale record the caller already checked. This prevents deleting a newer PID record written by another starter.

Data flow: It takes the stale record the caller saw, obtains the reservation lock, rereads the PID file, and compares the current record with the expected one. If they match, it removes the PID file and returns Missing. If the file changed, it returns the new state instead.

Call relations: is_starting_or_running and stop call this after discovering that a recorded process is no longer active. It uses acquire_reservation_lock and read_pid_file_state_with_lock_held to make cleanup safe against races.

Call graph: calls 2 internal fn (acquire_reservation_lock, read_pid_file_state_with_lock_held); called by 2 (is_starting_or_running, stop); 1 external calls (remove_file).

async fn acquire_reservation_lock(&self) -> Result<fs::File>

Purpose: Obtains exclusive access to the PID reservation lock file. This is the guard that keeps two tasks from starting or cleaning up the same managed process at the same time.

Data flow: It opens or creates the lock file, then repeatedly tries to take an exclusive non-blocking file lock until it succeeds or a timeout expires. On success it returns the open file, whose lifetime keeps the lock held. On timeout or lock error it returns an error.

Call relations: start calls this before reserving or publishing a PID file. refresh_after_stale_record calls it before deleting a stale record. Lower-level try_lock_file performs the actual operating-system lock attempt.

Call graph: calls 1 internal fn (try_lock_file); called by 2 (refresh_after_stale_record, start); 4 external calls (bail!, new, now, sleep).

async fn open_stderr_log(&self) -> Result<fs::File>

Purpose: Creates the stderr log file used by the detached managed process. Stderr is where programs usually write warnings and errors, so saving it gives later diagnostics something useful to show.

Data flow: It derives a stderr-log path from the PID file path, opens the file for writing, creates it if needed, and truncates old contents. It returns the open file so start can attach it to the child process.

Call relations: start calls this just before spawning the child process. It relies on stderr_log_file_for_pid_file so the write path matches the later read path used by read_stderr_log_tail.

Call graph: calls 1 internal fn (stderr_log_file_for_pid_file); called by 1 (start); 1 external calls (new).

fn command_args(&self) -> Vec<&'static str>

Purpose: Chooses the command-line arguments used to launch the managed process. The arguments differ depending on whether this backend starts the normal app server, the app server with remote control, or the update loop.

Data flow: It reads the backend’s command kind and remote-control setting, then returns a list of fixed argument strings. No files or processes are changed.

Call relations: start calls this while building the child process command. The returned arguments are passed directly to the Codex binary.

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

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

Purpose: Chooses any special environment variable needed when launching the process. In particular, it marks remote control as disabled when the app server is started without remote-control support.

Data flow: It reads the backend’s command kind. For an app server with remote control disabled, it returns a key-value pair to put in the child process environment. For remote-control-enabled app servers and the update loop, it returns nothing.

Call relations: start calls this after setting command arguments. If it returns a value, start adds that environment variable before spawning the child.

Call graph: called by 1 (start).

fn terminate_process(&self, pid: u32) -> Result<()>

Purpose: Sends the normal “please exit” shutdown request for the backend’s managed process. It is a small method wrapper so the rest of the backend can call one common operation.

Data flow: It receives a process ID and checks the backend command kind. It then calls the lower-level terminate_process helper to send the operating-system termination signal. It returns success if the signal was sent or the process is already gone, otherwise an error.

Call relations: start calls this to clean up a child if startup fails after spawning. stop calls it as the first, polite shutdown step before considering a forceful kill.

Call graph: calls 1 internal fn (terminate_process); called by 2 (start, stop).

fn force_terminate_process(&self, pid: u32) -> Result<()>

Purpose: Forcefully stops the managed process after graceful shutdown has taken too long. For the update loop, it kills the whole process group so child processes are not left behind.

Data flow: It receives a process ID and looks at the backend command kind. For the normal app server, it sends a force-kill signal to that PID. For the update loop, it sends the force-kill signal to the process group rooted at that PID. It returns success if the target is killed or already gone, otherwise an error.

Call relations: stop calls this only after the grace period has passed. It delegates to force_terminate_process or force_terminate_process_group depending on what kind of managed command was started.

Call graph: calls 2 internal fn (force_terminate_process, force_terminate_process_group); called by 1 (stop).

async fn record_is_active(&self, record: &PidRecord) -> Result<bool>

Purpose: Checks whether a PID record still describes the same live process. This protects the daemon from trusting a stale PID file after a crash or process-ID reuse.

Data flow: It receives a PID record containing a process ID and start time. It asks process_matches_record whether that process exists and still has the same start time. It returns true only when both match.

Call relations: is_starting_or_running, start, and stop call this before trusting a PID record. It is the backend-level wrapper around the platform-specific process check.

Call graph: calls 1 internal fn (process_matches_record); called by 3 (is_starting_or_running, start, stop).

async fn read_stderr_log_tail(pid_file: &Path) -> Result<Option<PidLogTail>>

Purpose: Reads the last part of the stderr log associated with a PID file. This is used to add helpful recent server output to error messages without loading an entire large log.

Data flow: It takes a PID file path, derives the matching stderr-log path, and asks read_log_tail to read up to the configured byte limit. If there is useful content, it wraps the path and contents in a PidLogTail; if the log is missing or empty, it returns None.

Call relations: The broader daemon error-reporting helper append_stderr_log_tail_context calls this. It connects the PID-file naming convention to the generic tail-reading helper.

Call graph: calls 2 internal fn (read_log_tail, stderr_log_file_for_pid_file); called by 1 (append_stderr_log_tail_context).

fn stderr_log_file_for_pid_file(pid_file: &Path) -> PathBuf

Purpose: Builds the stderr-log file path that belongs to a PID file. This keeps log naming consistent between the writer and the reader.

Data flow: It receives a PID file path and returns a sibling-style path with the extension changed to stderr.log. It does not touch the filesystem.

Call relations: open_stderr_log uses this when preparing the child process’s stderr output. read_stderr_log_tail uses the same helper later when looking for that saved output.

Call graph: called by 2 (open_stderr_log, read_stderr_log_tail); 1 external calls (with_extension).

async fn read_log_tail(path: &Path, byte_limit: u64) -> Result<Option<String>>

Purpose: Reads only the end of a log file, up to a byte limit, and returns clean text. This avoids pulling a very large stderr log into memory just to show recent messages.

Data flow: It opens the given path. Missing files produce None. Empty files produce None. For non-empty files, it seeks near the end, reads the remaining bytes, drops a partial first line if it started in the middle, converts bytes to text even if some characters are invalid, trims trailing whitespace, and returns the text if anything remains.

Call relations: read_stderr_log_tail calls this after choosing the stderr-log path. It is the reusable low-level reader that turns a log file into a small diagnostic snippet.

Call graph: called by 1 (read_stderr_log_tail); 4 external calls (Start, from_utf8_lossy, new, open).

fn process_exists(pid: u32) -> bool

Purpose: Checks whether a Unix process ID currently refers to an existing process. It treats “permission denied” as still existing, because the process may be alive even if this user cannot signal it.

Data flow: It receives a numeric process ID, converts it to the operating system’s PID type, and uses a harmless signal check. It returns true if the process exists or access is denied, and false if the PID is invalid or the process is gone.

Call relations: process_matches_record calls this before and after reading process start time. It is the quick existence check used before doing the more precise start-time comparison.

Call graph: called by 1 (process_matches_record); 3 external calls (last_os_error, kill, try_from).

fn terminate_process(_pid: u32) -> Result<()>

Purpose: Sends a normal Unix termination signal to a process, or reports unsupported shutdown on non-Unix platforms. A normal termination signal gives the process a chance to clean up.

Data flow: It receives a process ID. On Unix, it converts the ID, sends SIGTERM, and treats “no such process” as success because the desired end state is already true. Other signal errors become an error result. On unsupported platforms, it returns an unsupported-operation error.

Call relations: PidBackend::terminate_process delegates here. This helper is used during normal stop and during startup cleanup if a child was spawned but could not be recorded correctly.

Call graph: called by 1 (terminate_process); 4 external calls (bail!, last_os_error, kill, try_from).

fn force_terminate_process(_pid: u32) -> Result<()>

Purpose: Sends a forceful kill signal to one process, or reports unsupported shutdown on non-Unix platforms. This is used only after the normal shutdown request has not worked.

Data flow: It receives a process ID. On Unix, it converts the ID, sends SIGKILL, and treats “no such process” as success. Other errors are returned with context. On unsupported platforms, it returns an unsupported-operation error.

Call relations: PidBackend::force_terminate_process calls this for the normal app server after stop’s grace period expires.

Call graph: called by 1 (force_terminate_process); 4 external calls (bail!, last_os_error, kill, try_from).

fn force_terminate_process_group(_pid: u32) -> Result<()>

Purpose: Forcefully kills a whole Unix process group rooted at a given PID, or reports unsupported updater shutdown on non-Unix platforms. This helps stop an updater and any child processes it may have started.

Data flow: It receives the updater’s process ID. On Unix, it converts the ID and sends SIGKILL to the negative PID, which means the process group. If the group is already gone, it counts as success; other errors are returned. On unsupported platforms, it returns an unsupported-operation error.

Call relations: PidBackend::force_terminate_process calls this for update-loop backends. stop reaches it only after graceful shutdown has exceeded the grace period.

Call graph: called by 1 (force_terminate_process); 4 external calls (bail!, last_os_error, kill, try_from).

async fn process_matches_record(_record: &PidRecord) -> Result<bool>

Purpose: Verifies that a PID record points to the same process that was originally recorded. This avoids the classic PID-file bug where a process ID gets reused by an unrelated program.

Data flow: It receives a PID record. On Unix, it first checks whether the process exists, then reads that process’s start time and compares it with the recorded start time. If the process disappears during the check, it returns false. On non-Unix platforms, it returns false because this PID-management mode is not supported.

Call relations: PidBackend::record_is_active calls this whenever higher-level code needs to trust or reject a PID record. It combines process_exists and read_process_start_time into the stronger identity check.

Call graph: calls 2 internal fn (process_exists, read_process_start_time); called by 1 (record_is_active).

fn try_lock_file(_file: &fs::File) -> Result<bool>

Purpose: Attempts to take an exclusive file lock without waiting forever. A file lock is a small operating-system guard that lets one process say, “I am using this file right now.”

Data flow: It receives an open file. On Unix, it asks the operating system for an exclusive non-blocking lock and returns true if it got it, false if someone else already holds it, or an error for unexpected failures. On unsupported platforms, it reports that PID-managed startup is unsupported.

Call relations: acquire_reservation_lock repeatedly calls this until the lock is acquired or times out. reservation_lock_is_active and inspect_empty_pid_reservation also use it to tell whether another starter is currently holding the reservation.

Call graph: called by 3 (acquire_reservation_lock, inspect_empty_pid_reservation, reservation_lock_is_active); 4 external calls (as_raw_fd, bail!, last_os_error, flock).

async fn reservation_lock_is_active(_path: &Path) -> Result<bool>

Purpose: Checks whether the PID reservation lock is currently held by someone else. This helps distinguish “no PID file because nothing is happening” from “a process is in the middle of starting.”

Data flow: It opens or creates the lock file, tries to lock it, and returns true if the lock could not be taken because another holder has it. If the lock can be taken, it returns false. On non-Unix platforms, it returns false.

Call relations: read_pid_file_state calls this when the PID file is missing. That lets a missing PID file still be reported as Starting if startup has reserved the lock but has not yet published the PID record.

Call graph: calls 1 internal fn (try_lock_file); called by 1 (read_pid_file_state); 1 external calls (new).

async fn inspect_empty_pid_reservation(
    _pid_path: &Path,
    _lock_path: &Path,
) -> Result<EmptyPidReservation>

Purpose: Figures out what an empty PID file means. An empty PID file can be a live startup reservation, a stale leftover, or a file that was filled just after it was first read.

Data flow: It opens the lock file and tries to take the lock. If another holder has it, it returns Active. If it gets the lock, it rereads the PID file: missing or still-empty means stale, and the empty file may be removed; non-empty contents are parsed as a PID record and returned. On non-Unix platforms, it treats the reservation as stale.

Call relations: read_pid_file_state calls this only after it reads an empty PID file. This helper resolves the race between a starter writing the PID record and another task reading the file.

Call graph: calls 1 internal fn (try_lock_file); called by 1 (read_pid_file_state); 5 external calls (Record, new, read_to_string, remove_file, from_str).

async fn read_process_start_time(pid: u32) -> Result<String>

Purpose: Reads a process’s start time from the operating system so the PID record can identify a specific process, not just a reusable number. On Unix it uses the ps command for this.

Data flow: It receives a process ID, runs ps to ask for that process’s long start time, checks that the command succeeded, converts the output to text, trims it, and returns the start-time string. If ps fails, the output is not valid UTF-8, or the start time is empty, it returns an error.

Call relations: start calls this immediately after spawning the child so it can write a trustworthy PID record. process_matches_record calls it later to confirm that the recorded PID still belongs to the same process.

Call graph: called by 2 (start, process_matches_record); 3 external calls (from_utf8, bail!, new).

async fn probe(socket_path: &Path) -> Result<ProbeInfo>

Purpose: Checks whether an app-server is reachable through a given control socket and returns basic information about it. It protects callers from waiting forever by applying a short timeout.

Data flow: It receives a socket path. It starts the real probe work, waits up to the configured timeout, and either returns a ProbeInfo with the server version or returns an error explaining that probing failed or took too long.

Call relations: Higher-level daemon actions such as starting, stopping, restarting, checking version, and waiting for readiness call this when they need to know whether the app-server is alive. It delegates the actual conversation to probe_inner and wraps that conversation in a timeout.

Call graph: calls 1 internal fn (probe_inner); called by 9 (bootstrap_locked, restart, set_remote_control_locked, start, stop, try_restart_if_running, version, wait_until_ready, probe_app_server_version); 1 external calls (timeout).

async fn probe_inner(socket_path: &Path) -> Result<ProbeInfo>

Purpose: Carries out the actual probe conversation with the app-server. It connects, introduces the daemon, confirms initialization, closes the connection, and extracts the server version.

Data flow: It receives a socket path. It opens a WebSocket connection, sends an initialize request without experimental API support, sends an "initialized" notification after the response arrives, closes the WebSocket, then turns the response's user-agent string into a ProbeInfo value.

Call relations: probe calls this after adding the timeout wrapper. Inside, it uses connect to open the link, initialize to perform the JSON-RPC handshake, send_message to send the final notification, and parse_version_from_user_agent to pull out the version.

Call graph: calls 4 internal fn (connect, initialize, parse_version_from_user_agent, send_message); called by 1 (probe); 1 external calls (Notification).

async fn connect(socket_path: &Path) -> Result<WebSocketStream<UnixStream>>

Purpose: Opens the local control connection to the app-server and turns it into a WebSocket stream. This gives the rest of the code a standard way to send and receive protocol messages.

Data flow: It receives a filesystem path to a Unix socket. It connects to that socket, performs the WebSocket upgrade, and returns a WebSocket stream ready for JSON-RPC messages. If either step fails, it returns an error that includes the socket path.

Call relations: probe_inner uses this before probing the server. Other flows, such as retrying connections or enabling and disabling remote control, also call it when they need a live channel to the app-server.

Call graph: calls 1 internal fn (connect); called by 5 (probe_inner, connect_with_retry, disable_remote_control, enable_remote_control, run_enable_remote_control_scenario); 1 external calls (client_async).

async fn initialize(
    websocket: &mut WebSocketStream<S>,
    experimental_api: bool,
) -> Result<InitializeResponse>

Purpose: Performs the JSON-RPC initialize handshake with the app-server. This is the formal introduction where the daemon says who it is and what capabilities it wants to use.

Data flow: It receives an open WebSocket and a flag saying whether to request the experimental API. It builds an initialize request containing the daemon's name, title, package version, and optional capabilities, sends it, then reads messages until it finds the response with the matching request id. It parses that response into an InitializeResponse and returns it.

Call relations: probe_inner uses this during probing, and initialize_client uses it when setting up a fuller client session. It relies on send_message to write the request and read_message, with a timeout, to wait for the correct response.

Call graph: calls 2 internal fn (read_message, send_message); called by 2 (probe_inner, initialize_client); 5 external calls (default, Request, env!, to_value, timeout).

async fn send_message(
    websocket: &mut WebSocketStream<S>,
    message: &JSONRPCMessage,
) -> Result<()>

Purpose: Serializes one JSON-RPC message and sends it over an open WebSocket. It is the shared outgoing-message doorway for this client code.

Data flow: It receives a WebSocket and a JSONRPCMessage value. It converts the message into a JSON string, wraps that string as a WebSocket text frame, sends it, and returns success or an error from serialization or sending.

Call relations: initialize uses it to send the initialize request, and probe_inner uses it to send the initialized notification. Other remote-control flows also call it whenever they need to send requests, replies, or status messages over the same protocol.

Call graph: called by 8 (initialize, probe_inner, initialize_client, send_remote_control_request, accept_initialized_client, disable_remote_control_retries_without_params_for_older_servers, send_remote_control_status, serve_enable_remote_control_scenario); 3 external calls (send, to_string, Text).

async fn read_message(websocket: &mut WebSocketStream<S>) -> Result<JSONRPCMessage>

Purpose: Waits for the next usable JSON-RPC message from a WebSocket. It ignores non-text WebSocket frames because this protocol expects JSON text.

Data flow: It receives a WebSocket. It repeatedly reads incoming frames, skips anything that is not text, and parses the first text payload as a JSONRPCMessage. If the socket closes or the text is not valid protocol JSON, it returns an error.

Call relations: initialize uses this while waiting for the initialize response. Other remote-control code uses it to read responses, accept initialized clients, and wait for status messages.

Call graph: called by 6 (initialize, read_remote_control_response, accept_initialized_client, disable_remote_control_retries_without_params_for_older_servers, serve_enable_remote_control_scenario, wait_for_remote_control_status); 1 external calls (next).

fn parse_version_from_user_agent(user_agent: &str) -> Result<String>

Purpose: Extracts the version number from the app-server's user-agent string. A user-agent is a short identity string, usually shaped like "name/version" followed by extra details.

Data flow: It receives a user-agent string. It looks for the slash that separates the name from the version, then takes the first non-empty word after the slash. It returns that version as a string, or an error if the expected version part is missing.

Call relations: probe_inner calls this after initialization, because the server version is reported inside the initialize response's user-agent field. The tests in this file check both the successful and failing cases.

Call graph: called by 1 (probe_inner).

fn parses_version_from_codex_user_agent()

Purpose: Checks that a normal Codex-style user-agent string yields the expected version number. This protects the probe result from silently breaking if the parsing rules change.

Data flow: It gives parse_version_from_user_agent a realistic user-agent string containing a name, version, operating-system details, and another product token. It expects the function to return "1.2.3".

Call relations: This test directly exercises parse_version_from_user_agent. It stands apart from the network code so the version parsing rule can be verified without opening any socket.

Call graph: 1 external calls (assert_eq!).

fn rejects_user_agent_without_version()

Purpose: Checks that a user-agent with no slash-and-version part is rejected. This makes sure malformed server identity strings do not produce misleading version information.

Data flow: It passes a string containing only the product name into parse_version_from_user_agent. It expects an error rather than a fake or empty version.

Call relations: This test directly exercises the failure path of parse_version_from_user_agent. Together with the successful parsing test, it documents the minimum format the probe code expects from the server.

Call graph: 1 external calls (assert!).

async fn background_server_check(config: &Config) -> DoctorCheck

Purpose: Builds the complete doctor result for the background app-server. It gathers visible clues from the daemon’s state directory and, only if a socket already exists, checks whether the daemon can answer with its version.

Data flow: It receives the current configuration, especially the Codex home folder. From that folder it builds paths for the daemon state directory, settings file, PID files, and control socket. It records readable detail lines, asks socket_status whether the socket looks usable, adds the server mode, and returns a DoctorCheck with an OK or warning status plus human-readable details.

Call relations: This is the top-level check in this file. The tests call it directly to verify the doctor output. During its work it delegates small file-reporting details to push_file_detail, asks external code for the control socket path, and calls socket_status for the only live probe.

Call graph: calls 3 internal fn (new, push_file_detail, socket_status); called by 2 (failed_version_probe_reports_unavailable, not_running_background_server_stays_ok_without_version); 3 external calls (new, app_server_control_socket_path, format!).

fn push_file_detail(details: &mut Vec<String>, label: &str, path: &Path)

Purpose: Adds one clear detail line about whether a specific file exists and is actually a file. It helps the doctor output explain what was found without treating missing files as errors.

Data flow: It receives the growing list of detail strings, a label such as “settings,” and a file path. It checks the path’s filesystem metadata. It then appends a message saying the path is a file, missing, not a file, or could not be checked because of an error.

Call relations: background_server_check calls this for the settings file and both PID files. It does not decide the overall health by itself; it only supplies facts for the final doctor report.

Call graph: called by 1 (background_server_check); 2 external calls (format!, metadata).

fn server_mode(state_dir: &Path) -> &'static str

Purpose: Decides whether the daemon appears to be in persistent or ephemeral mode. In plain terms, persistent means there is a saved settings file; ephemeral means the daemon state looks temporary or not configured to persist.

Data flow: It receives the daemon state directory path. It checks whether settings.json exists there as a file. It returns the text persistent if it does, otherwise ephemeral.

Call relations: background_server_check uses this result when writing the final detail lines, so users can see what style of background server setup the state directory suggests.

Call graph: 1 external calls (join).

fn check_status(&self) -> CheckStatus

Purpose: Converts the socket-specific result into the general doctor status used by the rest of the doctor system. Not running and running are both OK; a stale or unreachable socket is a warning.

Data flow: It reads the current SocketStatus value. If the value says there is no running daemon or there is a reachable daemon, it returns CheckStatus::Ok. If the value says the socket exists but could not be reached, it returns CheckStatus::Warning.

Call relations: background_server_check uses this when building the final DoctorCheck. This keeps the rule about what counts as healthy close to the socket status type itself.

fn summary(&self) -> &'static str

Purpose: Provides the short one-line summary shown in the doctor result for each socket state. This is the user-facing headline for the background server check.

Data flow: It reads the current SocketStatus value and maps it to a fixed sentence: not running, running, or stale/unreachable. It returns that sentence for use in the final report.

Call relations: background_server_check uses this summary when it creates the final doctor check. The test cases also indirectly rely on these exact summaries.

fn detail_label(&self) -> &'static str

Purpose: Provides a compact label for the detailed status line. It is shorter than the summary and is meant to fit inside the doctor details list.

Data flow: It reads the current SocketStatus value and returns a short label: not running, running, or stale or unreachable.

Call relations: background_server_check uses this after probing the socket so the details include a simple status line. Tests check for these labels in the report.

fn app_server_version_detail(&self) -> Option<String>

Purpose: Creates an optional detail line about the app-server version. It only includes a version when the daemon answered, or an “unavailable” message when a socket existed but the version probe failed.

Data flow: It reads the current SocketStatus. For NotRunning, it returns nothing because there is no daemon to ask. For Running, it returns a detail string containing the version. For StaleOrUnreachable, it returns a detail string explaining that the version could not be fetched and includes the shortened error.

Call relations: background_server_check calls this after socket_status so the final report can include version information when useful. The tests check both the running and failed-probe behavior.

Call graph: 1 external calls (format!).

async fn socket_status(socket_path: &Path) -> SocketStatus

Purpose: Figures out what the existing control socket means. If there is no socket, the daemon is treated as not running; if there is a socket, it tries to ask the daemon for its version.

Data flow: It receives the control socket path. First it checks whether that path exists. If not, it returns NotRunning. If it exists, it calls the app-server daemon probe. A successful reply becomes Running(version). A failed reply becomes StaleOrUnreachable(shortened error).

Call relations: background_server_check calls this as the active part of the diagnostic. When probing fails, it hands the error to concise_probe_error so the final user message stays readable.

Call graph: calls 1 internal fn (concise_probe_error); called by 1 (background_server_check); 4 external calls (exists, Running, StaleOrUnreachable, probe_app_server_version).

fn concise_probe_error(err: &anyhow::Error, socket_path: &Path) -> String

Purpose: Turns a possibly long, noisy socket probe error into a short message suitable for doctor output. It avoids dumping an entire local path or an overly long technical error into the report.

Data flow: It receives the original error and the socket path. It turns the error into text, replaces the full socket path with the friendlier phrase control socket, collapses extra whitespace, and truncates the result to a fixed length. If the message is empty, it returns unknown error.

Call relations: socket_status calls this only when the version probe fails. Its output is stored inside SocketStatus::StaleOrUnreachable, which later appears in the version detail line.

Call graph: called by 1 (socket_status); 3 external calls (display, to_string, format!).

async fn test_config(codex_home: PathBuf) -> Config

Purpose: Builds a test configuration rooted in a temporary Codex home directory. This lets tests run without touching the user’s real files.

Data flow: It receives a temporary path. It feeds that path into the configuration builder and awaits the finished configuration. It returns the resulting Config or fails the test if the config cannot be built.

Call relations: The async tests call this before running background_server_check, so each test has an isolated fake home directory.

Call graph: 1 external calls (default).

fn create_socket_placeholder(config: &Config)

Purpose: Creates a fake control socket path for tests. It does not create a real working daemon socket; it creates a placeholder file so the production code believes something is present and then the probe fails.

Data flow: It receives a test configuration, asks external app-server code for the expected socket path, creates the parent directory, and writes an empty file at that path.

Call relations: The failed-probe test calls this to simulate a stale or unusable socket. That setup drives background_server_check into the warning path.

Call graph: 3 external calls (app_server_control_socket_path, create_dir_all, write).

async fn not_running_background_server_stays_ok_without_version()

Purpose: Verifies that an absent background server is not considered a doctor failure. This matters because not every user should have the daemon running all the time.

Data flow: It creates a temporary directory, builds a test config pointing there, and runs background_server_check. It then checks that the result is OK, says the server is not running, includes the not running detail, and does not include any version line.

Call relations: This test calls test_config and then the main background_server_check. It protects the intended behavior that missing daemon files are normal, not alarming.

Call graph: calls 1 internal fn (background_server_check); 4 external calls (assert!, assert_eq!, test_config, tempdir).

fn running_background_server_reports_app_server_version()

Purpose: Verifies the formatting and health rules for an already-known running socket status. It checks that a running daemon is OK and that its version is shown.

Data flow: It creates a SocketStatus::Running value with version 1.2.3. It calls the status helper methods and compares their outputs to the expected OK status, summary, label, and version detail.

Call relations: This test exercises the SocketStatus methods directly rather than going through filesystem setup or socket probing. It protects the small translation layer from internal status values to user-facing text.

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

async fn failed_version_probe_reports_unavailable()

Purpose: Verifies that a present but unusable socket becomes a warning with a clear explanation. This is the case that often explains why clients cannot connect.

Data flow: It creates a temporary Codex home, builds a config, and writes a fake socket placeholder. Then it runs background_server_check and checks that the result is a warning, says the socket is stale or unreachable, includes that status detail, and includes a version-unavailable detail.

Call relations: This test uses test_config and create_socket_placeholder to set up the stale-socket scenario, then calls background_server_check. It confirms the path from socket probing failure to user-facing warning.

Call graph: calls 1 internal fn (background_server_check); 5 external calls (assert!, assert_eq!, create_socket_placeholder, test_config, tempdir).

async fn enable_remote_control(socket_path: &Path) -> Result<RemoteControlReadyStatus>

Purpose: Turns remote control on using the app server socket path. This is the simple entry point for callers that expect the server socket to already be available.

Data flow: It receives a filesystem path to the app server socket. It opens a WebSocket connection to that path, then passes the live connection to the timed enable flow. It returns a RemoteControlReadyStatus describing whether remote control connected, is still connecting, errored, or timed out.

Call relations: Higher-level code such as ensure_remote_control_ready and set_remote_control_locked calls this when remote control should be enabled. This function only opens the connection; it hands the actual protocol conversation to enable_remote_control_with_timeout.

Call graph: calls 2 internal fn (connect, enable_remote_control_with_timeout); called by 2 (ensure_remote_control_ready, set_remote_control_locked).

async fn disable_remote_control(socket_path: &Path) -> Result<RemoteControlReadyStatus>

Purpose: Turns remote control off using the app server socket path. It performs the startup handshake, sends a disable request, and returns the server’s final status.

Data flow: It receives a socket path, connects to the app server, initializes the client session, builds disable parameters with ephemeral set to true, and sends the remoteControl/disable request. If the server replies successfully, the response is converted into RemoteControlReadyStatus; the WebSocket is then closed. If the newer parameter format is rejected, the request is retried without parameters.

Call relations: set_remote_control_locked uses this when the system needs to disable remote control. The test disable_remote_control_retries_without_params_for_older_servers also calls it to prove the old-server fallback works. Internally it relies on initialize_client and request_remote_control_with_legacy_fallback.

Call graph: calls 3 internal fn (connect, initialize_client, request_remote_control_with_legacy_fallback); called by 2 (set_remote_control_locked, disable_remote_control_retries_without_params_for_older_servers); 2 external calls (from, to_value).

async fn enable_remote_control_with_connect_retry(
    socket_path: &Path,
    connect_timeout: Duration,
    connect_retry_delay: Duration,
) -> Result<RemoteControlReadyStatus>

Purpose: Turns remote control on, but first keeps trying to connect for a limited amount of time. This is useful when the app server may still be starting up.

Data flow: It receives a socket path, a total connection timeout, and a pause between attempts. It repeatedly tries to connect until one attempt succeeds or the timeout expires. Once connected, it runs the normal timed enable flow and returns the resulting RemoteControlReadyStatus.

Call relations: enable_remote_control_on_socket calls this when it wants a more patient startup path. This function delegates connection retrying to connect_with_retry and delegates the enable conversation to enable_remote_control_with_timeout.

Call graph: calls 2 internal fn (connect_with_retry, enable_remote_control_with_timeout); called by 1 (enable_remote_control_on_socket).

async fn enable_remote_control_with_timeout(
    websocket: &mut WebSocketStream<S>,
    ready_timeout: Duration,
) -> Result<RemoteControlReadyStatus>

Purpose: Runs the full remote-control enable conversation on an already-open WebSocket. It also waits for a later status update if the first answer says the connection is still in progress.

Data flow: It receives a mutable WebSocket and a maximum wait time. It initializes the client session, sends remoteControl/enable with ephemeral parameters, and converts the response into RemoteControlReadyStatus. If that status is Connecting, it keeps reading status notifications until the status changes or the timeout expires. It closes the socket before returning the latest status.

Call relations: enable_remote_control, enable_remote_control_with_connect_retry, and the enable tests all use this as the core enable workflow. It calls initialize_client first, uses request_remote_control_with_legacy_fallback for compatibility, and calls wait_for_remote_control_status only when the server says more waiting is needed.

Call graph: calls 3 internal fn (initialize_client, request_remote_control_with_legacy_fallback, wait_for_remote_control_status); called by 3 (enable_remote_control, enable_remote_control_with_connect_retry, run_enable_remote_control_scenario); 3 external calls (close, from, to_value).

async fn initialize_client(websocket: &mut WebSocketStream<S>) -> Result<()>

Purpose: Performs the required opening handshake with the app server before remote-control requests are sent. It tells the server this client supports the experimental API and then sends the standard initialized notification.

Data flow: It receives an open WebSocket. It calls the shared client initialization routine with experimental API support enabled, then sends an "initialized" notification over the same socket. It returns nothing on success, or an error if either step fails.

Call relations: disable_remote_control and enable_remote_control_with_timeout call this before making remote-control requests. It relies on the shared client module to send the actual JSON-RPC messages.

Call graph: calls 2 internal fn (initialize, send_message); called by 2 (disable_remote_control, enable_remote_control_with_timeout); 1 external calls (Notification).

async fn send_remote_control_request(
    websocket: &mut WebSocketStream<S>,
    request_id: RequestId,
    method: &str,
    params: Option<serde_json::Value>,
) -> Result<()>

Purpose: Builds and sends one JSON-RPC request for a remote-control method. It centralizes the request shape so enable, disable, and fallback requests are sent consistently.

Data flow: It receives the WebSocket, a request ID, a method name such as remoteControl/enable, and optional JSON parameters. It wraps those pieces into a JSON-RPC request message and writes it to the socket. It returns success after the message is sent, or an error with the method name included for context.

Call relations: request_remote_control_with_legacy_fallback calls this for the first request and, when needed, for the retry without parameters. It hands the completed message to the shared client send function.

Call graph: calls 1 internal fn (send_message); called by 1 (request_remote_control_with_legacy_fallback); 1 external calls (Request).

async fn request_remote_control_with_legacy_fallback(
    websocket: &mut WebSocketStream<S>,
    method: &str,
    params: serde_json::Value,
) -> Result<T>

Purpose: Sends a remote-control request in the modern format, then retries in an older format if the server says the parameters are invalid. This keeps new clients working with older app servers.

Data flow: It receives a WebSocket, a method name, and JSON parameters. It sends the request with parameters and waits for the matching response. If the result is successful, it returns the parsed response. If the server reports the JSON-RPC invalid-parameters error, it sends the same request again with no parameters. If that also fails for invalid parameters, it returns an error.

Call relations: disable_remote_control and enable_remote_control_with_timeout use this so they do not need to know about protocol-version differences. It sends requests through send_remote_control_request and reads answers through read_remote_control_response.

Call graph: calls 2 internal fn (read_remote_control_response, send_remote_control_request); called by 2 (disable_remote_control, enable_remote_control_with_timeout); 1 external calls (anyhow!).

async fn connect_with_retry(
    socket_path: &Path,
    connect_timeout: Duration,
    connect_retry_delay: Duration,
) -> Result<WebSocketStream<codex_uds::UnixStream>>

Purpose: Keeps trying to connect to the app server socket until the server is ready or a deadline passes. It turns a short startup race into a controlled wait.

Data flow: It receives the socket path, the maximum time to keep trying, and the delay between tries. It repeatedly calls the shared connect function. On the first successful connection it returns the WebSocket. If time runs out, it returns the final connection error with a clearer message saying the app server did not become ready.

Call relations: enable_remote_control_with_connect_retry uses this before starting the enable protocol. It relies on the shared client connection function and sleeps between failed attempts.

Call graph: calls 1 internal fn (connect); called by 1 (enable_remote_control_with_connect_retry); 2 external calls (now, sleep).

async fn read_remote_control_response(
    websocket: &mut WebSocketStream<S>,
    request_id: &RequestId,
    method: &str,
) -> Result<RemoteControlRpcResponse<T>>

Purpose: Waits for the response to a specific remote-control request and ignores unrelated messages that may arrive first. It also recognizes the special invalid-parameters error used for legacy fallback.

Data flow: It receives a WebSocket, the request ID it is waiting for, and the method name for error messages. It reads messages with a timeout. If it finds the matching success response, it parses the JSON result into the expected response type. If it finds the matching invalid-parameters error, it returns a special InvalidParams marker. Other matching errors become failures, remote-control status notifications are ignored here, and unrelated messages are skipped.

Call relations: request_remote_control_with_legacy_fallback calls this after each request it sends. This function uses remote_control_status_notification to identify status notifications that should not interrupt waiting for the request response.

Call graph: calls 2 internal fn (read_message, remote_control_status_notification); called by 1 (request_remote_control_with_legacy_fallback); 3 external calls (anyhow!, Success, timeout).

async fn wait_for_remote_control_status(
    websocket: &mut WebSocketStream<S>,
    mut latest: RemoteControlReadyStatus,
    ready_timeout: Duration,
) -> Result<RemoteControlReadyStatus>

Purpose: After enable returns "Connecting", this waits for a later notification that says remote control has connected or failed. If no final status arrives in time, it returns the latest status marked as timed out.

Data flow: It receives a WebSocket, the latest known status, and a maximum wait time. It reads messages until the deadline. Non-notification messages and unrelated notifications are ignored. When a remote-control status-change notification arrives, it becomes the new latest status. If that status is no longer Connecting, it is returned immediately. If the timer expires, the latest status is returned with timed_out set to true.

Call relations: enable_remote_control_with_timeout calls this only when the enable response says remote control is still Connecting. It uses remote_control_status_notification to recognize and parse the relevant notifications.

Call graph: calls 2 internal fn (read_message, remote_control_status_notification); called by 1 (enable_remote_control_with_timeout); 3 external calls (from, now, timeout).

fn remote_control_status_notification(
    notification: &JSONRPCNotification,
) -> Option<RemoteControlStatusChangedNotification>

Purpose: Checks whether a JSON-RPC notification is a remote-control status update and, if so, parses its details. It is the filter that separates useful status updates from other server chatter.

Data flow: It receives a notification message. If the method name is not remoteControl/status/changed, it returns nothing. If the method matches, it takes the notification parameters and tries to parse them into a RemoteControlStatusChangedNotification. A valid parse returns that status object; missing or malformed data returns nothing.

Call relations: read_remote_control_response uses this to skip status notifications while waiting for a direct response. wait_for_remote_control_status uses it to find the status updates that decide whether enabling is finished.

Call graph: called by 2 (read_remote_control_response, wait_for_remote_control_status); 1 external calls (from_value).

fn from(notification: RemoteControlStatusChangedNotification) -> Self

Purpose: Converts a remote-control status-change notification into the simpler status object returned by this client. It keeps the connection status, server name, and environment ID, while dropping fields that the caller does not need here.

Data flow: It receives a RemoteControlStatusChangedNotification from the protocol layer. It copies out the status, server name, and environment ID, ignores the installation ID, and creates a RemoteControlReadyStatus with timed_out set to false. The timeout flag is only set later by waiting logic if a deadline expires.

Call relations: wait_for_remote_control_status uses this conversion when a status notification arrives. The wider enable flow then returns the converted value to callers once the status is final or timed out.

async fn enable_remote_control_uses_connected_enable_response_without_later_notification() -> Result<()>

Purpose: Checks that enabling remote control returns immediately when the enable response already says Connected. No later notification should be required in that case.

Data flow: The test builds a fake scenario where the server response says Connected and no follow-up notification is sent. It runs the enable flow and compares the returned RemoteControlReadyStatus with the expected connected status, server name, environment ID, and timed_out false.

Call relations: This test drives the shared helper run_enable_remote_control_scenario, which creates the fake server and calls the real enable_remote_control_with_timeout logic. It proves the enable path does not wait unnecessarily.

Call graph: 4 external calls (from_millis, remote_control_status, run_enable_remote_control_scenario, assert_eq!).

async fn enable_remote_control_waits_for_connected_notification() -> Result<()>

Purpose: Checks that enabling remote control waits for a later notification when the first response says Connecting. This verifies the normal asynchronous connection flow.

Data flow: The test creates a fake server response with Connecting and then sends a status-change notification with Connected. It runs the enable flow and expects the final returned status to be Connected with the environment ID from the notification.

Call relations: This test uses run_enable_remote_control_scenario to exercise enable_remote_control_with_timeout and its wait_for_remote_control_status step. It shows that later notifications can update the initial response.

Call graph: 4 external calls (from_secs, remote_control_status, run_enable_remote_control_scenario, assert_eq!).

async fn enable_remote_control_reports_connecting_after_timeout() -> Result<()>

Purpose: Checks that the client reports a timeout instead of waiting forever when remote control stays Connecting. This protects callers from hanging on a server that never sends a final status.

Data flow: The test sets up a fake server that replies Connecting and sends no useful follow-up notification before a short timeout. The enable flow returns the same Connecting status, but with timed_out set to true.

Call relations: This test goes through run_enable_remote_control_scenario into enable_remote_control_with_timeout. It specifically validates the timeout branch inside wait_for_remote_control_status.

Call graph: 4 external calls (from_millis, remote_control_status, run_enable_remote_control_scenario, assert_eq!).

async fn enable_remote_control_returns_errored_enable_response() -> Result<()>

Purpose: Checks that an Errored response from the server is returned as-is rather than treated as something to wait on. This keeps failures visible to callers immediately.

Data flow: The test configures the fake server to answer the enable request with Errored. The enable flow converts that response into RemoteControlReadyStatus and returns it with timed_out false.

Call relations: Like the other enable tests, it uses run_enable_remote_control_scenario to reach the real enable logic. It confirms that only Connecting triggers wait_for_remote_control_status.

Call graph: 4 external calls (from_millis, remote_control_status, run_enable_remote_control_scenario, assert_eq!).

async fn enable_remote_control_retries_without_params_for_older_servers() -> Result<()>

Purpose: Checks that enabling remote control still works with older servers that reject the newer ephemeral parameter. This protects backward compatibility.

Data flow: The fake server first rejects the enable request with the invalid-parameters error. The client then retries the same method without parameters, receives a Connected response, and returns the expected connected status.

Call relations: This test uses run_enable_remote_control_scenario and the fake server helper to exercise request_remote_control_with_legacy_fallback through the real enable path.

Call graph: 4 external calls (from_millis, remote_control_status, run_enable_remote_control_scenario, assert_eq!).

async fn disable_remote_control_retries_without_params_for_older_servers() -> Result<()>

Purpose: Checks that disabling remote control also supports the old-server fallback when ephemeral parameters are rejected. It mirrors the enable fallback test for the disable method.

Data flow: The test creates a temporary Unix socket and a fake server. The fake server accepts initialization, receives a disable request with ephemeral true, rejects it as invalid parameters, then verifies the client sends a second disable request with no parameters. It responds Disabled, and the test checks that disable_remote_control returns the expected disabled status.

Call relations: This test calls the real disable_remote_control function while a spawned fake server uses accept_initialized_client and protocol messages to simulate an older app server.

Call graph: calls 5 internal fn (read_message, send_message, disable_remote_control, from, bind); 9 external calls (new, accept_initialized_client, remote_control_status, Error, Response, assert_eq!, panic!, to_value, spawn).

async fn run_enable_remote_control_scenario(
        scenario: EnableScenario,
    ) -> Result<RemoteControlReadyStatus>

Purpose: Sets up a reusable fake-server environment for enable-flow tests. It keeps the individual tests focused on the scenario they care about.

Data flow: It receives an EnableScenario describing what the fake server should send and whether it should reject parameters. It creates a temporary socket, starts the fake server task, connects a real client WebSocket, runs enable_remote_control_with_timeout, waits for the server task to finish, and returns the status produced by the client.

Call relations: The enable tests call this helper. It connects the test scenario to serve_enable_remote_control_scenario on the server side and the real enable_remote_control_with_timeout on the client side.

Call graph: calls 3 internal fn (connect, enable_remote_control_with_timeout, bind); 3 external calls (new, serve_enable_remote_control_scenario, spawn).

async fn serve_enable_remote_control_scenario(
        listener: UnixListener,
        scenario: EnableScenario,
    ) -> Result<()>

Purpose: Acts as a fake app server for enable-flow tests. It speaks just enough of the protocol to test the client’s behavior.

Data flow: It receives a Unix socket listener and an EnableScenario. It accepts and initializes a client, optionally sends an initial status notification, reads and checks the enable request, optionally rejects the first request to trigger fallback, sends the configured enable response, and optionally sends a later status notification. If no later notification is configured, it waits briefly so the client can hit its timeout path.

Call relations: run_enable_remote_control_scenario spawns this helper as the server side of each enable test. It uses accept_initialized_client to handle the handshake and send_remote_control_status for status notifications.

Call graph: calls 3 internal fn (read_message, send_message, from); 9 external calls (from_millis, accept_initialized_client, send_remote_control_status, Error, Response, assert_eq!, panic!, to_value, sleep).

async fn accept_initialized_client(
        mut listener: UnixListener,
    ) -> Result<WebSocketStream<codex_uds::UnixStream>>

Purpose: Accepts one fake-server WebSocket connection and verifies the client performs the required initialization handshake. It gives tests a ready-to-use WebSocket after setup is complete.

Data flow: It receives a Unix socket listener, accepts a connection, upgrades it to a WebSocket, reads the initialize request, checks that experimentalApi is true, sends a normal initialize response, then reads and verifies the initialized notification. It returns the WebSocket positioned after the handshake.

Call relations: The fake server helpers call this before testing enable or disable requests. It mirrors the initialization that initialize_client performs on the real client side.

Call graph: calls 3 internal fn (read_message, send_message, accept); 5 external calls (Response, assert_eq!, panic!, json!, accept_async).

async fn send_remote_control_status(
        websocket: &mut WebSocketStream<S>,
        status: RemoteControlStatusChangedNotification,
    ) -> Result<()>

Purpose: Sends a remote-control status-change notification from a fake server to the client during tests. It avoids repeating the notification-building code in each scenario.

Data flow: It receives a WebSocket and a status notification object. It serializes the status into JSON, wraps it in a JSON-RPC notification named remoteControl/status/changed, and sends it over the socket. It returns success or the send error.

Call relations: serve_enable_remote_control_scenario calls this when a test scenario includes an initial or follow-up status notification. The real client later recognizes these messages through remote_control_status_notification.

Call graph: calls 1 internal fn (send_message); 2 external calls (Notification, to_value).

fn remote_control_status(
        status: RemoteControlConnectionStatus,
        environment_id: Option<&str>,
    ) -> RemoteControlStatusChangedNotification

Purpose: Builds a standard remote-control status notification for tests. It fills in repeated test values so each test only has to choose the connection status and optional environment ID.

Data flow: It receives a RemoteControlConnectionStatus and an optional environment ID string. It returns a RemoteControlStatusChangedNotification with the chosen status, the shared fake server name, the shared fake installation ID, and the optional environment ID converted to an owned string.

Call relations: Most enable tests and the disable fallback test use this helper to create realistic protocol status objects. Those objects are then sent by fake server helpers or converted into response payloads.

fn configured_thread_config_loader(config: &Config) -> Arc<dyn ThreadConfigLoader>

Purpose: Chooses how thread-specific configuration should be loaded. If the main config names a remote endpoint, it builds a remote loader; otherwise it uses a no-op loader that does nothing.

Data flow: It receives the loaded Config. It reads the optional experimental thread config endpoint, turns that into either a RemoteThreadConfigLoader or a NoopThreadConfigLoader, wraps it in shared ownership, and returns it.

Call relations: During server startup, run_main_with_transport_options calls this after the first config preload. The returned loader is installed into ConfigManager so later config reloads can include discovered thread configuration.

Call graph: calls 1 internal fn (new); called by 1 (run_main_with_transport_options); 1 external calls (new).

async fn shutdown_signal() -> IoResult<ShutdownSignal>

Purpose: Waits for an operating-system shutdown signal and classifies it as either forceable or graceful-only. This lets the server know whether it should drain work or prepare for a possible forced restart.

Data flow: It reads process signals from the operating system. On Unix it waits for Ctrl-C, terminate, or hangup signals; on non-Unix systems it waits for Ctrl-C. It returns the kind of shutdown signal, or an input/output error if signal listening fails.

Call relations: The main processor loop inside run_main_with_transport_options waits on this when graceful signal handling is enabled. Its result is handed to ShutdownState::on_signal, which records whether shutdown has begun or should be forced.

Call graph: 4 external calls (hangup, terminate, select!, ctrl_c).

fn requested(&self) -> bool

Purpose: Answers whether a shutdown has already been requested. It is a small readability helper for the main loop.

Data flow: It reads the ShutdownState value and returns the stored requested flag without changing anything.

Call relations: The processor loop uses this while deciding whether to keep watching running assistant turns during graceful restart.

fn forced(&self) -> bool

Purpose: Answers whether shutdown has moved from graceful waiting to forced stopping. This helps the server decide whether to drain work or abandon cleanup.

Data flow: It reads the ShutdownState value and returns the stored forced flag without changing anything.

Call relations: The processor loop checks this before listening for more shutdown signals and again at teardown to choose between graceful cleanup and aborting cleanup tasks.

fn on_signal(
        &mut self,
        signal: ShutdownSignal,
        connection_count: usize,
        running_turn_count: usize,
    )

Purpose: Records that the process received a shutdown signal. The first signal starts graceful draining; a later forceable signal changes the shutdown into a forced one.

Data flow: It receives the signal type, the current number of connections, and the number of running assistant turns. It updates the shutdown state and logs what is happening. It does not return a value.

Call relations: The processor loop calls this after shutdown_signal returns. Its updated state is later interpreted by ShutdownState::update to decide whether the server can finish.

Call graph: 2 external calls (info!, matches!).

fn update(&mut self, running_turn_count: usize, connection_count: usize) -> ShutdownAction

Purpose: Decides whether the server should keep waiting or finish shutdown now. It lets graceful restart wait for active assistant work, unless shutdown was forced.

Data flow: It receives the current running assistant turn count and connection count. It checks the stored shutdown flags, logs progress when useful, updates the last logged count, and returns either Noop or Finish.

Call relations: The processor loop calls this on each pass. When it returns Finish, run_main_with_transport_options cancels transport acceptors and asks the outbound router to disconnect all clients.

Call graph: 1 external calls (info!).

fn config_warning_from_error(
    summary: impl Into<String>,
    err: &std::io::Error,
) -> ConfigWarningNotification

Purpose: Turns a configuration loading error into a warning object that can be shown to clients. It preserves both the human message and, when available, the exact file location of the problem.

Data flow: It receives a short summary and an input/output error. It asks config_error_location whether the error includes a config file path and text range, then builds a ConfigWarningNotification with summary, details, optional path, and optional range.

Call relations: run_main_with_transport_options uses this when strict config mode is off and user configuration cannot be loaded. It lets the server continue with defaults while still telling clients what went wrong.

Call graph: calls 1 internal fn (config_error_location); called by 1 (run_main_with_transport_options); 2 external calls (into, to_string).

fn config_error_location(err: &std::io::Error) -> Option<(String, AppTextRange)>

Purpose: Extracts the file path and text range from a configuration error, if that information is available. This helps editors point users at the exact broken part of a config file.

Data flow: It receives an input/output error. It looks inside the wrapped error for a ConfigLoadError, converts the config error’s path and range into app-server protocol types, and returns them if found.

Call relations: config_warning_from_error calls this while building a client-visible warning. If this function finds nothing, the warning still exists but has no clickable location.

Call graph: called by 1 (config_warning_from_error); 1 external calls (get_ref).

fn exec_policy_warning_location(err: &ExecPolicyError) -> (Option<String>, Option<AppTextRange>)

Purpose: Finds where an execution policy parsing problem happened. An execution policy is a rule file that controls what commands may run.

Data flow: It receives an ExecPolicyError. For parse errors, it returns the policy file path and, if known, the exact text range. For other error types it returns no location.

Call relations: run_main_with_transport_options calls this after checking execution policy warnings. The location becomes part of a ConfigWarningNotification sent to clients.

Call graph: called by 1 (run_main_with_transport_options).

fn app_text_range(range: &CoreTextRange) -> AppTextRange

Purpose: Converts a text range from the core configuration format into the app-server protocol format. This keeps file-location warnings understandable to clients.

Data flow: It receives a core TextRange with start and end line and column numbers. It copies those numbers into the protocol’s TextRange type and returns it.

Call relations: config_error_location uses this when translating config loading errors into client-facing warning data.

fn project_config_warning(config: &Config) -> Option<ConfigWarningNotification>

Purpose: Builds a warning when project-local Codex settings are disabled because a project is not trusted. This tells users why local config, hooks, or execution policies are not being applied.

Data flow: It receives the current Config. It scans all config layers, finds disabled project layers, collects each folder and reason, and returns one combined ConfigWarningNotification if any were found.

Call relations: run_main_with_transport_options calls this during startup after loading configuration. Any returned warning is added to the startup warning list sent to initialized clients.

Call graph: called by 1 (run_main_with_transport_options); 3 external calls (new, concat!, format!).

fn from_env_value(value: Option<&str>) -> Self

Purpose: Interprets the LOG_FORMAT environment value. Only the value json, ignoring case and surrounding spaces, enables JSON logs; everything else uses normal text logs.

Data flow: It receives an optional string. It trims and lowercases it, compares it to json, and returns either LogFormat::Json or LogFormat::Default.

Call relations: log_format_from_env calls this after reading the environment. The test functions in this file check the accepted and rejected values.

Call graph: called by 1 (log_format_from_env).

fn log_format_from_env() -> LogFormat

Purpose: Reads the process environment to decide how stderr logs should be formatted. This gives operators a simple switch for structured JSON logging.

Data flow: It reads LOG_FORMAT from the environment, passes the optional value to LogFormat::from_env_value, and returns the chosen LogFormat.

Call relations: run_main_with_transport_options calls this while installing tracing, which is the Rust logging and diagnostics system used by the server.

Call graph: calls 1 internal fn (from_env_value); called by 1 (run_main_with_transport_options); 1 external calls (var).

async fn run_main(
    arg0_paths: Arg0DispatchPaths,
    cli_config_overrides: CliConfigOverrides,
    loader_overrides: LoaderOverrides,
    strict_config: bool,
    default_analytics_enabled: bool,

Purpose: Starts the app server with the normal defaults. It is the convenient public entry used when the caller does not need custom transport or runtime options.

Data flow: It receives startup paths, command-line config overrides, loader overrides, strict-config choice, and the default analytics setting. It fills in standard choices such as stdio transport, VS Code session source, default WebSocket auth settings, and default runtime options, then awaits run_main_with_transport_options.

Call relations: This is the simpler front door into the runtime. It delegates all real setup and looping work to run_main_with_transport_options.

Call graph: calls 2 internal fn (default, run_main_with_transport_options); 1 external calls (default).

fn default() -> Self

Purpose: Defines the normal runtime behavior for the app server. By default, plugin startup work runs, remote control preference is resolved from saved state, and shutdown signal handling is installed.

Data flow: It takes no input. It creates and returns an AppServerRuntimeOptions value with the project’s default choices.

Call relations: run_main uses this when it calls run_main_with_transport_options, so ordinary server startup gets a consistent set of runtime behaviors.

Call graph: called by 1 (run_main).

async fn run_main_with_transport_options(
    arg0_paths: Arg0DispatchPaths,
    cli_config_overrides: CliConfigOverrides,
    loader_overrides: LoaderOverrides,
    strict_config: bool,
    default_a

Purpose: Builds and runs the full app server. It loads configuration, opens transports, starts background tasks, routes messages, watches shutdown signals, and performs cleanup.

Data flow: It receives startup paths, config override settings, transport choice, session source, authentication settings, analytics defaults, and runtime options. It creates channels for incoming events and outgoing messages, loads config, initializes telemetry and the SQLite state database, starts local or remote connection acceptors, creates MessageProcessor, and runs the processor and outbound router tasks until shutdown. It returns Ok when the server stops cleanly or an input/output error if startup cannot continue.

Call relations: run_main calls this for the default path, and specialized callers can call it directly with custom transports. Inside, it calls many helper functions in this file for config warnings, log format, database recovery, test-only loader overrides, thread config loading, and analytics transport naming, then hands request work to MessageProcessor and outgoing writes to route_outgoing_envelope.

Call graph: calls 27 internal fn (app_server_startup_lock_path, policy_from_settings, analytics_rpc_transport, analytics_events_client_from_config, new, config_warning_from_error, configured_thread_config_loader, new, exec_policy_warning_location, init_sqlite_state_db_with_fresh_start_on_corruption (+15 more)); called by 1 (run_main); 33 external calls (clone, new, new, default, from_default_env, new, new, new, new, default (+15 more)).

async fn init_sqlite_state_db_with_fresh_start_on_corruption(
    config: &Config,
) -> anyhow::Result<StateDbInitResult>

Purpose: Opens the local SQLite state database, and if it appears damaged, moves the damaged files aside so the server can start with a fresh database. SQLite is the small embedded database used for local server state.

Data flow: It receives the current Config, repeatedly tries to initialize the rollout state database, and watches for corruption-style failures. On corruption or a blocking file where the database folder should be, it backs up the bad database files, records what was moved, and tries again. It returns the database handle plus an optional recovery notice, or an error if recovery fails.

Call relations: run_main_with_transport_options calls this during startup before message processing begins. It uses sqlite_home_is_blocking_file, sqlite_recovery_notice, and emit_state_db_backup_warning to decide when and how to recover and how to warn users.

Call graph: calls 3 internal fn (emit_state_db_backup_warning, sqlite_home_is_blocking_file, sqlite_recovery_notice); called by 1 (run_main_with_transport_options); 8 external calls (new, new, anyhow!, backup_runtime_db_for_fresh_start, is_sqlite_corruption_error, runtime_db_path_for_corruption_error, format!, try_init).

fn sqlite_home_is_blocking_file(database_path: &Path) -> bool

Purpose: Checks for a filesystem mistake where the database’s parent folder is actually a file. That situation blocks SQLite from creating its database in the expected place.

Data flow: It receives a database path. It looks at the path’s parent, reads its filesystem metadata if possible, and returns true only when that parent exists as a regular file.

Call relations: init_sqlite_state_db_with_fresh_start_on_corruption calls this after a database open failure. A true result is treated similarly to corruption: the runtime tries a fresh-start backup path.

Call graph: called by 1 (init_sqlite_state_db_with_fresh_start_on_corruption); 1 external calls (parent).

fn sqlite_recovery_notice(
    recovered_databases: &[RecoveredSqliteDatabase],
) -> Option<SqliteRecoveryNotice>

Purpose: Creates a user-facing notice describing any database files that were backed up during recovery. Without this, the server could silently rebuild state after moving damaged files.

Data flow: It receives a list of recovered database records. If the list is empty it returns None. Otherwise it formats each original database path and backup folder into a details string and returns a SqliteRecoveryNotice.

Call relations: init_sqlite_state_db_with_fresh_start_on_corruption calls this after database initialization finally succeeds. The notice is later turned into a startup configuration warning by run_main_with_transport_options.

Call graph: called by 1 (init_sqlite_state_db_with_fresh_start_on_corruption); 2 external calls (is_empty, iter).

fn emit_state_db_backup_warning(message: &str)

Purpose: Logs a warning about database backup or recovery, and prints it directly to stderr if logging has not been set up yet. This makes early startup recovery visible.

Data flow: It receives a message string. It sends the message through tracing as a warning, then checks whether a tracing dispatcher has already been installed; if not, it also writes the message to standard error.

Call relations: init_sqlite_state_db_with_fresh_start_on_corruption calls this whenever it detects damage, moves files, or reports final backup locations.

Call graph: called by 1 (init_sqlite_state_db_with_fresh_start_on_corruption); 3 external calls (eprintln!, has_been_set, warn!).

fn test_user_config_file_from_env() -> Option<std::path::PathBuf>

Purpose: Reads a debug-only environment variable that can point the app server at a test user config file. In non-debug builds it always returns nothing.

Data flow: In debug builds, it reads CODEX_APP_SERVER_TEST_USER_CONFIG_FILE, ignores empty values, and returns the path if present. In release builds, it returns None without reading a useful value.

Call relations: run_main_with_transport_options calls this before loading config, then passes the result to loader_overrides_with_test_user_config_file.

Call graph: called by 1 (run_main_with_transport_options); 1 external calls (var_os).

fn loader_overrides_with_test_user_config_file(
    mut loader_overrides: LoaderOverrides,
    test_user_config_file: Option<std::path::PathBuf>,
) -> IoResult<LoaderOverrides>

Purpose: Applies the debug-only test user config path to LoaderOverrides. This lets tests and development runs use a specific config file without changing real user settings.

Data flow: It receives existing LoaderOverrides and an optional path. In debug builds, if a path exists, it verifies that it is absolute, stores it as the user config path, logs a warning, and returns the modified overrides. In non-debug builds it ignores the path and returns the original overrides.

Call relations: run_main_with_transport_options calls this at the start of config setup. The debug_test_user_config_file_overrides_loader_path test also calls it to verify that the override is applied.

Call graph: calls 1 internal fn (from_absolute_path); called by 2 (run_main_with_transport_options, debug_test_user_config_file_overrides_loader_path); 1 external calls (warn!).

fn analytics_rpc_transport(transport: &AppServerTransport) -> AppServerRpcTransport

Purpose: Labels the server’s connection style for analytics. Stdio is reported separately; all socket, WebSocket, off, and remote-style modes are grouped as WebSocket transport for analytics purposes.

Data flow: It receives an AppServerTransport value. It matches the transport kind and returns the corresponding AppServerRpcTransport label.

Call relations: run_main_with_transport_options calls this when constructing MessageProcessorArgs, so analytics events from request processing include the broad RPC transport type.

Call graph: called by 1 (run_main_with_transport_options).

fn log_format_from_env_value_matches_json_values_case_insensitively()

Purpose: Checks that JSON logging is enabled by json regardless of letter case or surrounding spaces. This protects the operator-facing LOG_FORMAT behavior.

Data flow: It passes several string examples into LogFormat::from_env_value and asserts that each returns LogFormat::Json.

Call relations: This test exercises LogFormat::from_env_value directly. It does not take part in server runtime; it runs only under the test harness.

Call graph: 1 external calls (assert_eq!).

fn log_format_from_env_value_defaults_for_non_json_values()

Purpose: Checks that missing or non-json LOG_FORMAT values fall back to the normal text log format. This prevents accidental JSON logging from near-miss values like jsonl.

Data flow: It passes None, an empty string, text, and jsonl into LogFormat::from_env_value and asserts that each returns LogFormat::Default.

Call relations: This test covers the default branch used by log_format_from_env. It runs only during tests.

Call graph: 1 external calls (assert_eq!).

fn debug_test_user_config_file_overrides_loader_path()

Purpose: Verifies the debug-only path that lets developers override the user config file for app-server tests. It confirms that the override is stored as an absolute path.

Data flow: It creates a temporary config path, calls loader_overrides_with_test_user_config_file with default loader overrides and that path, then asserts that the returned overrides contain the same absolute path.

Call relations: This test calls loader_overrides_with_test_user_config_file directly. It is compiled only in debug builds, matching the debug-only feature it checks.

Call graph: calls 1 internal fn (loader_overrides_with_test_user_config_file); 3 external calls (assert_eq!, default, temp_dir).

fn new(
        request_id: ConnectionRequestId,
        span: Span,
        parent_trace: Option<W3cTraceContext>,
    ) -> Self

Purpose: Builds a saved context for one incoming client request. The context ties together the request’s connection-specific id, its tracing span, and any trace information inherited from the caller.

Data flow: It receives a connection-scoped request id, a tracing span, and optional parent trace data. It stores those pieces together in a RequestContext and returns it for later use when the server sends the final response or error.

Call relations: Request-processing code creates this context when a client request starts. Later, OutgoingMessageSender stores it, reads trace data from it, or removes it when the request is completed or the connection closes.

Call graph: called by 4 (process_client_request, process_request, connection_closed_clears_registered_request_contexts, send_response_clears_registered_request_context).

fn request_trace(&self) -> Option<W3cTraceContext>

Purpose: Returns the best trace identity available for this request. This lets later work stay linked to the original request in observability tools.

Data flow: It looks first at the current span to see whether it has W3C trace context, which is a standard way to pass trace ids between systems. If the span has none, it falls back to the parent trace saved when the request arrived.

Call relations: Higher-level thread startup code asks for this when it needs to continue the same trace across later work. It relies on the tracing helper span_w3c_trace_context to extract trace data from the span.

Call graph: called by 1 (thread_start_inner); 1 external calls (span_w3c_trace_context).

fn span(&self) -> Span

Purpose: Gives callers a copy of the tracing span for this request. A span is a named section of work used for logs and performance tracing.

Data flow: It reads the stored span, clones the handle, and returns the clone. The original context remains unchanged.

Call relations: Request dispatch and execution paths use this span when running work or sending the final outgoing message, so logs and send failures are connected back to the request that caused them.

Call graph: called by 3 (dispatch_initialized_client_request, run_request_with_context, thread_start_inner); 1 external calls (clone).

fn record_turn_id(&self, turn_id: &str)

Purpose: Adds the conversation turn id to this request’s trace span. This makes logs easier to connect to a specific turn in a thread.

Data flow: It receives a turn id string and records it as a field on the stored tracing span. It does not return anything; it enriches the trace data in place.

Call relations: OutgoingMessageSender uses this through its request-context table when later code learns which turn belongs to an already-registered request.

Call graph: 1 external calls (record).

fn new(
        outgoing: Arc<OutgoingMessageSender>,
        connection_ids: Vec<ConnectionId>,
        thread_id: ThreadId,
    ) -> Self

Purpose: Creates a sender that is pre-bound to one thread and a known set of client connections. This saves callers from repeatedly passing the same thread and connection information.

Data flow: It receives the shared outgoing sender, a list of connection ids, and a thread id. It wraps the connection list in shared storage and returns a ThreadScopedOutgoingMessageSender.

Call relations: Thread and turn handling code constructs this wrapper before emitting events or asking the client for thread-specific decisions. Many tests also create it to exercise thread-scoped behavior.

Call graph: called by 18 (command_execution_started_helper_emits_once, complete_command_execution_item_emits_declined_once_for_pending_command, guardian_command_execution_notifications_wrap_review_lifecycle, interrupted_subagent_activity_removes_missing_thread_watch, test_handle_token_count_event_emits_usage_and_rate_limits, test_handle_token_count_event_without_usage_info, test_handle_turn_complete_emits_completed_without_error, test_handle_turn_complete_emits_error_multiple_turns, test_handle_turn_complete_emits_failed_with_error, test_handle_turn_diff_emits_v2_notification (+8 more)); 1 external calls (new).

async fn send_request(
        &self,
        payload: ServerRequestPayload,
    ) -> (RequestId, oneshot::Receiver<ClientRequestResult>)

Purpose: Sends a server request to the clients attached to this thread and returns a way to wait for the client’s answer. This is used for things like asking for approval or input.

Data flow: It receives a request payload without an id. It asks the shared OutgoingMessageSender to assign an id, remember the callback, and send the request to this wrapper’s connections, tagged with this wrapper’s thread id. It returns the assigned request id and a one-shot receiver that will later contain the client result or error.

Call relations: Thread-specific event handling calls this when the server needs a response from the client. The real sending and callback bookkeeping are delegated to OutgoingMessageSender::send_request_to_connections.

Call graph: called by 1 (apply_bespoke_event_handling).

fn track_effective_permissions_approval_response(
        &self,
        request_id: RequestId,
        response: RequestPermissionsResponse,
    )

Purpose: Records analytics when a permissions approval request receives an effective response. This is measurement-only; it does not send a message to the client.

Data flow: It receives the request id and the permissions response. It gets the current time in milliseconds and sends the event to the analytics client stored on the shared outgoing sender.

Call relations: Thread-level code can call this after permission decisions. It uses now_unix_timestamp_ms so analytics events have a completion time.

Call graph: calls 1 internal fn (now_unix_timestamp_ms).

async fn send_server_notification(&self, notification: ServerNotification)

Purpose: Sends a notification to the clients attached to this thread. Notifications are one-way messages, like progress updates, that do not expect a reply.

Data flow: It receives a notification, records it with analytics, and checks whether this thread has any target connections. If there are none, it stops. Otherwise it asks the shared sender to deliver the notification to those connections.

Call relations: Turn and event handling code calls this for thread-local updates such as token counts, diffs, plans, errors, and completion notices. It delegates actual delivery to OutgoingMessageSender::send_server_notification_to_connections.

Call graph: called by 10 (apply_bespoke_event_handling, complete_command_execution_item, emit_turn_completed_with_status, handle_error_notification, handle_token_count_event, handle_turn_diff, handle_turn_plan_update, maybe_emit_hook_prompt_item_completed, maybe_emit_raw_response_item_completed, start_command_execution_item); 1 external calls (clone).

async fn send_global_server_notification(&self, notification: ServerNotification)

Purpose: Sends a notification to all clients instead of only this thread’s connections. This is useful for events that are not tied to one thread view.

Data flow: It receives a notification and passes it directly to the shared outgoing sender’s broadcast-style notification method. It does not inspect the thread’s connection list.

Call relations: Thread event handling uses this when a thread-scoped component needs to emit a global app-server notification.

Call graph: called by 1 (apply_bespoke_event_handling).

async fn abort_pending_server_requests(&self)

Purpose: Cancels all outstanding server requests for this thread because the turn state changed. This prevents old approval or input prompts from resolving after they are no longer valid.

Data flow: It creates an internal JSON-RPC error with an extra machine-readable reason, then asks the shared sender to cancel every pending request tagged with this thread id. Each waiting task receives that error.

Call relations: Thread event handling calls this during turn transitions. It relies on internal_error to build the error and on OutgoingMessageSender::cancel_requests_for_thread to do the cleanup.

Call graph: calls 1 internal fn (internal_error); called by 1 (apply_bespoke_event_handling); 1 external calls (json!).

async fn send_response(&self, request_id: ConnectionRequestId, response: T)

Purpose: Sends a successful response to a specific incoming client request. It is a convenience method for thread code that already holds the thread-scoped sender.

Data flow: It receives the connection-scoped request id and a typed response payload. It forwards both to the shared outgoing sender, which serializes the response and targets the correct connection.

Call relations: Thread event handling and interrupt-response code use this when they finish handling a client request successfully.

Call graph: called by 2 (apply_bespoke_event_handling, respond_to_pending_interrupts).

async fn send_error(
        &self,
        request_id: ConnectionRequestId,
        error: impl Into<JSONRPCErrorError>,
    )

Purpose: Sends an error response to a specific incoming client request. This is used when thread-level processing cannot complete the request normally.

Data flow: It receives the connection-scoped request id and an error-like value. It converts through the shared sender, which builds the JSON-RPC error message and sends it to the original connection.

Call relations: Thread event handling and rollback-failure handling call this when they need to answer a client request with failure.

Call graph: called by 2 (apply_bespoke_event_handling, handle_thread_rollback_failed).

fn new(
        sender: mpsc::Sender<OutgoingEnvelope>,
        analytics_events_client: AnalyticsEventsClient,
    ) -> Self

Purpose: Creates the central outgoing-message coordinator. It starts with no pending callbacks or request contexts and is ready to enqueue messages to the transport layer.

Data flow: It receives a channel sender for outgoing envelopes and an analytics client. It creates an atomic counter for future server request ids, two protected maps for pending state, and returns the assembled sender.

Call relations: Server setup and many tests construct this before any outgoing communication happens. Other methods on this type then use the stored channel and maps for all outgoing work.

Call graph: called by 38 (command_execution_started_helper_emits_once, complete_command_execution_item_emits_declined_once_for_pending_command, guardian_command_execution_notifications_wrap_review_lifecycle, interrupted_subagent_activity_removes_missing_thread_watch, test_handle_token_count_event_emits_usage_and_rate_limits, test_handle_token_count_event_without_usage_info, test_handle_turn_complete_emits_completed_without_error, test_handle_turn_complete_emits_error_multiple_turns, test_handle_turn_complete_emits_failed_with_error, test_handle_turn_diff_emits_v2_notification (+15 more)); 3 external calls (new, new, new).

async fn register_request_context(&self, request_context: RequestContext)

Purpose: Remembers tracing context for an incoming client request that has not yet received its final answer. This keeps later response sending tied to the original trace.

Data flow: It receives a RequestContext, locks the request-context table, and inserts it under the connection-scoped request id. If an unresolved context with the same id was already present, it logs a warning.

Call relations: Request-processing code calls this near the start of handling a client request. send_response_as and send_error later remove the context when the request is completed.

Call graph: 1 external calls (warn!).

async fn connection_closed(&self, connection_id: ConnectionId)

Purpose: Forgets unresolved request contexts for a client connection that has gone away. This prevents memory and trace state from being kept for a disconnected client.

Data flow: It receives a connection id, locks the request-context table, and removes every saved context whose connection id matches. It returns nothing.

Call relations: Connection cleanup code calls this when a transport connection closes. Tests verify that contexts for other still-open connections remain.

async fn request_trace_context(
        &self,
        request_id: &ConnectionRequestId,
    ) -> Option<W3cTraceContext>

Purpose: Looks up trace information for an unresolved incoming request. This lets later server work continue the same trace if the request is still known.

Data flow: It receives a connection-scoped request id, locks the context table, and finds the matching RequestContext. If present, it asks that context for its trace; otherwise it returns no trace.

Call relations: Higher-level request or thread startup code uses this when it needs trace continuity for work spawned after the initial request was registered.

async fn record_request_turn_id(
        &self,
        request_id: &ConnectionRequestId,
        turn_id: &str,
    )

Purpose: Attaches a turn id to the trace for an unresolved request. This improves diagnostics by linking request logs to the conversation turn they affected.

Data flow: It receives a connection-scoped request id and a turn id string. It locks the context table, finds the saved RequestContext if it exists, and records the turn id on that context’s span.

Call relations: Code that learns the turn id after request registration calls this to enrich tracing. It uses RequestContext::record_turn_id on the stored context.

async fn take_request_context(
        &self,
        request_id: &ConnectionRequestId,
    ) -> Option<RequestContext>

Purpose: Removes and returns the saved context for a request that is about to be answered. “Take” matters here because a request should only have one final response or error.

Data flow: It receives a connection-scoped request id, locks the context table, removes the matching entry, and returns it if one was present.

Call relations: send_response_as and send_error call this just before sending a final message. The returned context is used to attach tracing to the outgoing send.

Call graph: called by 2 (send_error, send_response_as).

async fn request_context_count(&self) -> usize

Purpose: Counts how many unresolved request contexts are currently stored. This exists only for tests.

Data flow: It locks the request-context table, reads its size, and returns that number. It does not change runtime behavior.

Call relations: Tests call this to prove that responses and disconnects clear saved request contexts instead of leaking them.

async fn send_request(
        &self,
        request: ServerRequestPayload,
    ) -> (RequestId, oneshot::Receiver<ClientRequestResult>)

Purpose: Broadcasts a server request to clients and returns a way to wait for a client response. It is the general version used when the request is not scoped to specific connections.

Data flow: It receives a request payload, passes it to send_request_to_connections with no target connection list and no thread id, and returns the generated request id plus the one-shot receiver.

Call relations: Callers use this for app-wide server-to-client requests. The real id creation, callback storage, and enqueueing are done by send_request_to_connections.

Call graph: calls 1 internal fn (send_request_to_connections).

fn next_request_id(&self) -> RequestId

Purpose: Creates the next unique id for a server request. Unique ids let later client responses be matched back to the right waiting task.

Data flow: It increments an atomic integer counter, which is a number safe to update from multiple tasks, and wraps the previous value as a JSON-RPC integer request id.

Call relations: send_request_to_connections calls this before building every outgoing server request.

Call graph: called by 1 (send_request_to_connections); 2 external calls (fetch_add, Integer).

async fn send_request_to_connections(
        &self,
        connection_ids: Option<&[ConnectionId]>,
        request: ServerRequestPayload,
        thread_id: Option<ThreadId>,
    ) -> (RequestId, o

Purpose: Sends a server request either to all clients or to selected connections, and records the callback needed to receive the answer. This is the heart of server-initiated request handling.

Data flow: It receives optional target connection ids, a request payload, and an optional thread id. It assigns a request id, turns the payload into a full ServerRequest, creates a one-shot channel for the eventual client answer, and stores that sender in the pending-callback map. Then it enqueues either a broadcast envelope or one targeted envelope per connection. If enqueueing fails, it logs the failure and removes the pending callback.

Call relations: OutgoingMessageSender::send_request and ThreadScopedOutgoingMessageSender::send_request both flow into this method. Later, notify_client_response, notify_client_error, or cancellation methods use the stored callback entry to finish the waiting receiver.

Call graph: calls 2 internal fn (track_server_request, next_request_id); called by 1 (send_request); 6 external calls (send, clone, request_with_id, Request, channel, warn!).

async fn replay_requests_to_connection_for_thread(
        &self,
        connection_id: ConnectionId,
        thread_id: ThreadId,
    )

Purpose: Resends still-pending thread-specific server requests to a connection. This is useful when a client connection joins or reconnects and needs to see prompts that are still waiting.

Data flow: It receives a connection id and thread id. It gathers pending requests for that thread, then enqueues each one as a targeted outgoing request to the given connection, logging if any enqueue fails.

Call relations: It builds on pending_requests_for_thread to find the work. The transport writer later receives the queued envelopes and writes them to the client.

Call graph: calls 1 internal fn (pending_requests_for_thread); 3 external calls (send, Request, warn!).

async fn notify_client_response(&self, id: RequestId, result: Result)

Purpose: Completes a pending server request when the client sends a successful response. It wakes the task that has been waiting for that answer.

Data flow: It receives the request id and the JSON result from the client. It removes the matching pending callback entry, records analytics for most typed responses, and sends Ok(result) through the one-shot callback. If no callback is found or the receiver is gone, it logs a warning.

Call relations: The client-response processing path calls this after decoding a client response. It uses take_request_callback to ensure the request is completed only once.

Call graph: calls 3 internal fn (track_server_response, take_request_callback, now_unix_timestamp_ms); 2 external calls (matches!, warn!).

async fn notify_client_error(&self, id: RequestId, error: JSONRPCErrorError)

Purpose: Completes a pending server request when the client answers with an error. The waiting server task receives that error instead of hanging.

Data flow: It receives a request id and JSON-RPC error. It removes the pending callback, records an aborted-request analytics event, and sends Err(error) to the waiting receiver. Missing callbacks or dropped receivers are logged.

Call relations: The client-error processing path calls this after decoding an error response from the client. It shares the same callback-removal helper used by successful responses and cancellation.

Call graph: calls 3 internal fn (track_server_request_aborted, take_request_callback, now_unix_timestamp_ms); 2 external calls (clone, warn!).

async fn cancel_request(&self, id: &RequestId) -> bool

Purpose: Cancels one pending server request by id. This is used when the server no longer wants to wait for the client’s answer.

Data flow: It receives a request id, removes the matching pending callback if present, records an aborted-request analytics event, and returns true if something was canceled or false if no pending request matched.

Call relations: Cancellation code calls this for a single request. It uses take_request_callback so later client responses for the same id will no longer find a waiter.

Call graph: calls 3 internal fn (track_server_request_aborted, take_request_callback, now_unix_timestamp_ms).

async fn cancel_all_requests(&self, error: Option<JSONRPCErrorError>)

Purpose: Cancels every pending server request. This is a broad cleanup path, for example during shutdown or major connection state changes.

Data flow: It drains the entire pending-callback map into a temporary list. For each entry it records an aborted-request analytics event, and if an error was supplied, it sends that error to the waiting receiver.

Call relations: Broader lifecycle code can use this to clear all outstanding server-to-client waits. It does not call take_request_callback because it drains the whole map at once.

Call graph: calls 2 internal fn (track_server_request_aborted, now_unix_timestamp_ms); 1 external calls (warn!).

async fn take_request_callback(
        &self,
        id: &RequestId,
    ) -> Option<(RequestId, PendingCallbackEntry)>

Purpose: Removes the pending callback for one server request and returns it. This is the small shared helper that makes completion and cancellation one-time actions.

Data flow: It receives a request id, locks the pending-callback map, removes the entry with that id, and returns both the id and the stored callback entry if found.

Call relations: notify_client_response, notify_client_error, and cancel_request all call this before finishing a pending request. Once it returns an entry, that request is no longer considered pending.

Call graph: called by 3 (cancel_request, notify_client_error, notify_client_response).

async fn pending_requests_for_thread(
        &self,
        thread_id: ThreadId,
    ) -> Vec<ServerRequest>

Purpose: Lists the still-pending server requests that belong to one thread. This lets the server replay or inspect outstanding prompts for that thread.

Data flow: It receives a thread id, locks the pending-callback map, filters entries whose stored thread id matches, clones their ServerRequest values, sorts them by request id, and returns the sorted list.

Call relations: replay_requests_to_connection_for_thread calls this before resending pending prompts to a connection. Tests also verify that the returned order is stable.

Call graph: called by 1 (replay_requests_to_connection_for_thread).

async fn cancel_requests_for_thread(
        &self,
        thread_id: ThreadId,
        error: Option<JSONRPCErrorError>,
    )

Purpose: Cancels every pending server request associated with one thread. This prevents old thread prompts from surviving after that thread’s turn changes or is aborted.

Data flow: It receives a thread id and optional error. It finds all pending callback entries tagged with that thread, removes them from the map, records an aborted-request analytics event for each, and sends the supplied error to each waiter if one was provided.

Call relations: ThreadScopedOutgoingMessageSender::abort_pending_server_requests uses this during turn transitions. Thread cleanup code can also call it directly when it needs to clear only one thread’s pending requests.

Call graph: calls 2 internal fn (track_server_request_aborted, now_unix_timestamp_ms); 2 external calls (with_capacity, warn!).

async fn send_response(&self, request_id: ConnectionRequestId, response: T)

Purpose: Sends a successful response to an incoming client request using any response type that can become a client response payload. It is a typed convenience wrapper.

Data flow: It receives a connection-scoped request id and a response value. It converts the response into ClientResponsePayload and forwards it to send_response_as.

Call relations: send_result calls this for successful results, and thread-scoped sending also delegates here through the shared sender.

Call graph: calls 1 internal fn (send_response_as); called by 1 (send_result); 1 external calls (into).

async fn send_response_as(
        &self,
        request_id: ConnectionRequestId,
        response: ClientResponsePayload,
    )

Purpose: Serializes and sends a successful JSON-RPC response to the exact connection that made the request. It also clears the saved request context because the request is now finished.

Data flow: It receives a connection-scoped request id and a ClientResponsePayload. It converts the payload into JSON-RPC response parts, tracks analytics if there is a typed response event, removes the saved RequestContext, and sends a response envelope to the original connection. If serialization fails, it sends an internal error response instead.

Call relations: OutgoingMessageSender::send_response calls this after type conversion. It uses take_request_context before final sending and hands the actual enqueue operation to send_outgoing_message_to_connection, or to send_error_inner on serialization failure.

Call graph: calls 4 internal fn (internal_error, send_error_inner, send_outgoing_message_to_connection, take_request_context); called by 1 (send_response); 3 external calls (into_jsonrpc_parts_and_payload, Response, format!).

async fn send_server_notification(&self, notification: ServerNotification)

Purpose: Broadcasts a server notification to clients. Notifications are one-way updates and do not create pending callbacks.

Data flow: It receives a notification and calls send_server_notification_to_connections with an empty target list, which this file treats as broadcast-to-all.

Call relations: Account login/import progress code calls this for app-wide notifications. The lower helper performs the actual enqueueing.

Call graph: calls 1 internal fn (send_server_notification_to_connections); called by 3 (send_chatgpt_login_completion_notifications, send_completed_import_notification, send_import_progress).

async fn send_server_notification_to_connections(
        &self,
        connection_ids: &[ConnectionId],
        notification: ServerNotification,
    )

Purpose: Sends a one-way notification either to all clients or to a selected list of connections. It is the main delivery path for app-server notifications.

Data flow: It receives a list of target connection ids and a notification. It wraps the notification as an outgoing app-server notification. If the list is empty, it enqueues one broadcast envelope. Otherwise it enqueues one targeted envelope per connection, logging any failures.

Call relations: Both global notification sending and thread-scoped notification sending use this. The transport layer later consumes the queued envelopes and writes the serialized JSON-RPC notification.

Call graph: called by 1 (send_server_notification); 6 external calls (send, clone, is_empty, AppServerNotification, trace!, warn!).

async fn send_server_notification_to_connection_and_wait(
        &self,
        connection_id: ConnectionId,
        notification: ServerNotification,
    )

Purpose: Sends a notification to one connection and waits until the transport says the write is complete. This is useful when ordering or flush confirmation matters.

Data flow: It receives a connection id and notification, wraps the notification, creates a one-shot completion channel, and enqueues a targeted envelope containing the completion sender. Then it waits for the completion receiver to fire, ignoring the final value.

Call relations: Code that needs stronger delivery timing can call this instead of the normal fire-and-forget notification method. The transport writer is expected to signal the included completion sender after writing.

Call graph: 6 external calls (send, clone, AppServerNotification, channel, trace!, warn!).

async fn send_error(
        &self,
        request_id: ConnectionRequestId,
        error: impl Into<JSONRPCErrorError>,
    )

Purpose: Sends an error response to the connection that made a client request. It also clears that request’s saved trace context.

Data flow: It receives a connection-scoped request id and an error-like value. It removes the request context, converts the error into a JSON-RPC error, and passes everything to send_error_inner.

Call relations: send_result calls this for failed results, and thread-scoped error sending delegates here. send_error_inner builds the outgoing error envelope.

Call graph: calls 2 internal fn (send_error_inner, take_request_context); called by 1 (send_result); 1 external calls (into).

async fn send_result(
        &self,
        request_id: ConnectionRequestId,
        result: std::result::Result<T, E>,
    )

Purpose: Turns a normal Rust result into either a success response or an error response. This gives callers one simple method when their work can succeed or fail.

Data flow: It receives a request id and a Result value. If the result is Ok, it sends the contained response. If it is Err, it sends the contained error.

Call relations: Request handlers can call this after finishing work instead of writing their own match. It delegates to send_response and send_error.

Call graph: calls 2 internal fn (send_error, send_response).

async fn send_error_inner(
        &self,
        request_context: Option<RequestContext>,
        request_id: ConnectionRequestId,
        error: JSONRPCErrorError,
    )

Purpose: Builds the actual outgoing error message and sends it to one connection. This keeps the common error-envelope construction in one place.

Data flow: It receives an optional request context, a connection-scoped request id, and a JSON-RPC error. It creates an OutgoingMessage::Error with the request id and error, then sends it to the request’s connection.

Call relations: send_error uses this for normal error responses, and send_response_as uses it when response serialization fails. It delegates enqueueing and trace instrumentation to send_outgoing_message_to_connection.

Call graph: calls 1 internal fn (send_outgoing_message_to_connection); called by 2 (send_error, send_response_as); 1 external calls (Error).

async fn send_outgoing_message_to_connection(
        &self,
        request_context: Option<RequestContext>,
        connection_id: ConnectionId,
        message: OutgoingMessage,
        message_kin

Purpose: Enqueues one already-built outgoing message for one connection, optionally under the original request’s tracing span. This is the final common send step for responses and errors.

Data flow: It receives optional request context, a connection id, a prepared outgoing message, and a label such as “response” or “error.” It creates a targeted envelope and sends it through the outgoing channel. If a context exists, it instruments the send with that span. If enqueueing fails, it logs a warning.

Call relations: send_response_as and send_error_inner call this after building final response or error messages. The transport layer later consumes the envelope.

Call graph: called by 2 (send_error_inner, send_response_as); 2 external calls (send, warn!).

fn now_unix_timestamp_ms() -> u64

Purpose: Returns the current time as milliseconds since the Unix epoch, which is the common timestamp starting point of January 1, 1970. Analytics events use this timestamp.

Data flow: It reads the system clock, subtracts the Unix epoch, converts the duration to milliseconds, and returns it as an unsigned integer. If the clock or conversion fails, it safely returns zero.

Call relations: Analytics-related methods call this when recording client responses, aborted requests, cancellations, and effective permissions approval responses.

Call graph: called by 6 (cancel_all_requests, cancel_request, cancel_requests_for_thread, notify_client_error, notify_client_response, track_effective_permissions_approval_response); 1 external calls (now).

fn verify_server_notification_serialization()

Purpose: Checks that a server notification serializes to the expected JSON-RPC method and parameters. This protects the wire format clients depend on.

Data flow: It builds an account-login-completed notification, wraps it as an outgoing app-server notification, serializes it to JSON, and compares the JSON to the expected object.

Call relations: This is a unit test for notification serialization. It does not run in production, but it guards the behavior used by notification-sending methods.

Call graph: 4 external calls (AccountLoginCompleted, nil, AppServerNotification, assert_eq!).

fn verify_account_login_completed_notification_serialization()

Purpose: Verifies the exact JSON shape for an account login completion notification. This ensures clients receive the method name and fields they expect.

Data flow: It creates a login-completed notification with a known UUID, converts it through OutgoingMessage serialization, and asserts that the resulting JSON matches the expected method and params.

Call relations: This test supports the notification path by catching accidental protocol changes before runtime.

Call graph: 4 external calls (AccountLoginCompleted, nil, AppServerNotification, assert_eq!).

fn verify_account_rate_limits_notification_serialization()

Purpose: Verifies the JSON format for account rate-limit updates. Rate-limit data has nested fields, so this test makes sure those fields stay correctly named and shaped.

Data flow: It builds a rate-limit snapshot notification, wraps it as an outgoing notification, serializes it, and compares the full JSON object to the expected structure.

Call relations: This test protects clients that listen for account/rateLimits/updated notifications sent through this file’s notification methods.

Call graph: 3 external calls (AccountRateLimitsUpdated, AppServerNotification, assert_eq!).

fn verify_account_updated_notification_serialization()

Purpose: Checks that account update notifications serialize correctly. This covers fields such as authentication mode and plan type.

Data flow: It creates an account-updated notification, wraps and serializes it, then asserts that the JSON method and parameter names match the protocol.

Call relations: This test guards the wire format used when OutgoingMessageSender broadcasts account update notifications.

Call graph: 3 external calls (AccountUpdated, AppServerNotification, assert_eq!).

fn verify_config_warning_notification_serialization()

Purpose: Checks the JSON shape for configuration warning notifications. These warnings tell clients about configuration problems in a predictable format.

Data flow: It builds a config warning with summary and details, serializes it as an outgoing notification, and compares the JSON to the expected method and params.

Call relations: This unit test protects the notification format consumed by clients when config warnings are sent.

Call graph: 3 external calls (ConfigWarning, AppServerNotification, assert_eq!).

fn verify_guardian_warning_notification_serialization()

Purpose: Verifies the JSON format for guardian warning notifications. These messages tell the client when an automatic safety review denied an action.

Data flow: It creates a guardian warning with a thread id and message, serializes it through OutgoingMessage, and asserts the expected JSON result.

Call relations: This test supports the same notification serialization used by thread-scoped notification sending.

Call graph: 3 external calls (GuardianWarning, AppServerNotification, assert_eq!).

fn verify_model_rerouted_notification_serialization()

Purpose: Checks that model rerouting notifications serialize with the correct method name and fields. Clients rely on this to explain why a model changed.

Data flow: It builds a model-rerouted notification with thread, turn, source model, target model, and reason, then serializes and compares it to expected JSON.

Call relations: This test protects notifications that can be sent by the server when model choice changes during a turn.

Call graph: 3 external calls (ModelRerouted, AppServerNotification, assert_eq!).

fn verify_model_verification_notification_serialization()

Purpose: Verifies the JSON format for model verification notifications. These notifications report model-related verification status to the client.

Data flow: It creates a notification with one verification value, serializes it as an outgoing notification, and checks the resulting JSON array and fields.

Call relations: This test guards a notification variant delivered through the same outgoing notification machinery.

Call graph: 4 external calls (ModelVerification, AppServerNotification, assert_eq!, vec!).

fn verify_turn_moderation_metadata_notification_serialization()

Purpose: Checks that turn moderation metadata notifications keep arbitrary metadata in the expected JSON location. This matters because metadata may be displayed or interpreted by clients.

Data flow: It builds a moderation metadata notification containing a small JSON object, serializes it, and compares the full output to the expected JSON-RPC method and params.

Call relations: This test protects the notification format used by turn-related event handling.

Call graph: 4 external calls (TurnModerationMetadata, AppServerNotification, assert_eq!, json!).

fn server_request_response_from_result_decodes_typed_response()

Purpose: Verifies that a raw client result for a server request can be decoded into the correct typed server response. This proves the callback result can be interpreted safely.

Data flow: It builds a command-execution approval request, feeds it a JSON result containing a decision, decodes that result into a typed ServerResponse, and checks the request id and decision.

Call relations: This test supports notify_client_response, which receives raw client results and records analytics after decoding typed responses.

Call graph: 4 external calls (Integer, assert_eq!, json!, panic!).

async fn send_response_routes_to_target_connection()

Purpose: Checks that a response goes only to the connection that made the request. This prevents one client from receiving another client’s answer.

Data flow: It creates an OutgoingMessageSender with a test channel, sends a response for connection 42, reads the queued envelope, and asserts that the envelope targets connection 42 with the expected response id and JSON result.

Call relations: This test exercises OutgoingMessageSender::send_response and the lower response enqueue path.

Call graph: calls 2 internal fn (disabled, new); 7 external calls (ThreadArchive, from_secs, Integer, new, assert_eq!, panic!, timeout).

async fn send_response_clears_registered_request_context()

Purpose: Verifies that sending a final response removes the saved request context. This prevents stale trace state from accumulating.

Data flow: It registers a RequestContext, confirms one context is stored, sends a response for that request, and then confirms the context table is empty.

Call relations: This test covers register_request_context, request_context_count, and the context-removal behavior inside send_response.

Call graph: calls 3 internal fn (disabled, new, new); 5 external calls (ThreadArchive, Integer, new, assert_eq!, info_span!).

async fn send_error_routes_to_target_connection()

Purpose: Checks that an error response is sent to the correct connection with the correct request id and error body.

Data flow: It creates a test sender, sends an internal error for a request on connection 9, reads the queued envelope, and asserts the connection id, outgoing message type, request id, and error match.

Call relations: This test exercises OutgoingMessageSender::send_error and the shared targeted-send path.

Call graph: calls 3 internal fn (disabled, internal_error, new); 6 external calls (from_secs, Integer, new, assert_eq!, panic!, timeout).

async fn send_server_notification_to_connection_and_wait_tracks_write_completion()

Purpose: Verifies that the wait-for-write notification method really waits until the transport signals completion. This protects code that needs a notification flushed before continuing.

Data flow: It starts send_server_notification_to_connection_and_wait in a task, reads the queued targeted envelope, checks that a write-completion sender is attached, sends the completion signal, and confirms the task finishes.

Call relations: This test covers OutgoingMessageSender::send_server_notification_to_connection_and_wait and the completion channel contract with the transport layer.

Call graph: calls 2 internal fn (disabled, new); 8 external calls (from_secs, ModelRerouted, new, assert!, assert_eq!, panic!, spawn, timeout).

async fn connection_closed_clears_registered_request_contexts()

Purpose: Checks that closing one connection removes only that connection’s request contexts. Contexts for other live connections must remain.

Data flow: It registers two contexts on different connections, confirms both are stored, closes one connection through connection_closed, and confirms only one context remains.

Call relations: This test exercises RequestContext::new, register_request_context, connection_closed, and request_context_count.

Call graph: calls 3 internal fn (disabled, new, new); 4 external calls (Integer, new, assert_eq!, info_span!).

async fn notify_client_error_forwards_error_to_waiter()

Purpose: Verifies that when a client returns an error for a pending server request, the waiting receiver gets that same error. This prevents approval or prompt waits from hanging silently.

Data flow: It sends a server request, keeps the returned receiver, calls notify_client_error with an internal error, waits on the receiver, and asserts that it receives Err(error).

Call relations: This test covers send_request, notify_client_error, and the pending callback table used between them.

Call graph: calls 4 internal fn (disabled, internal_error, new, new); 5 external calls (from_secs, new, ApplyPatchApproval, assert_eq!, timeout).

async fn pending_requests_for_thread_returns_thread_requests_in_request_id_order()

Purpose: Checks that pending requests for a thread are returned in request-id order. Stable ordering makes replay predictable for clients.

Data flow: It creates a thread-scoped sender, sends several thread-tagged requests, asks the shared sender for pending requests for that thread, and compares the returned ids to the send order.

Call relations: This test exercises ThreadScopedOutgoingMessageSender::send_request and OutgoingMessageSender::pending_requests_for_thread.

Call graph: calls 4 internal fn (disabled, new, new, new); 7 external calls (new, DynamicToolCall, FileChangeRequestApproval, ToolRequestUserInput, assert_eq!, json!, vec!).

async fn cancel_requests_for_thread_cancels_all_thread_requests()

Purpose: Verifies that canceling a thread’s pending requests resolves every waiter with the supplied error and leaves no pending requests behind.

Data flow: It sends two thread-scoped requests, calls cancel_requests_for_thread with an error, waits for both receivers, checks that both received the error, and confirms the thread has no pending requests.

Call relations: This test covers ThreadScopedOutgoingMessageSender::send_request, OutgoingMessageSender::cancel_requests_for_thread, and pending_requests_for_thread.

Call graph: calls 5 internal fn (disabled, internal_error, new, new, new); 9 external calls (new, from_secs, DynamicToolCall, ToolRequestUserInput, assert!, assert_eq!, json!, timeout, vec!).

fn new(
        outgoing: Arc<OutgoingMessageSender>,
        analytics_events_client: AnalyticsEventsClient,
        config: Arc<Config>,
        config_warnings: Vec<ConfigWarningNotification>,

Purpose: Creates an InitializeRequestProcessor with everything it needs to answer initialize requests: an outgoing message sender, analytics client, configuration, startup warnings, and the type of RPC transport being used. It is used during server setup so later request handling has one ready-made object to call.

Data flow: It receives shared messaging, analytics, configuration, warning, and transport objects. It stores them inside a new processor, wrapping the warning list so it can be cheaply shared when the processor is cloned. The result is a processor instance ready to be used for initialization work.

Call relations: A higher-level constructor calls this when wiring the app server together. After that setup step, the returned processor is the object other request-handling code uses when a client sends initialize or when initialization-related notifications need to be sent.

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

async fn initialize(
        &self,
        connection_id: ConnectionId,
        request_id: RequestId,
        params: InitializeParams,
        session: &ConnectionSessionState,
        // `Some(...

Purpose: Processes a client's initialize request and turns an uninitialized connection into an initialized one. It validates the client identity, stores the client's capabilities, records analytics, sends the initialize response, and optionally marks the connection as ready for outbound messages immediately.

Data flow: It starts with a connection id, request id, initialize parameters, the connection's current session state, and an optional shared boolean flag. It first refuses the request if the session is already initialized. It then extracts capabilities such as experimental API access, request attestation, and notification opt-outs. It validates the client name as a legal HTTP header value, because that name may be used as request metadata later. It writes the accepted details into the session state. If the client is not one of the special internal non-originating clients, it may update global client identity, including the default originator and user-agent suffix. It records an initialize analytics event, applies the residency setting from config, builds an InitializeResponse with user-agent, Codex home, and operating-system information, and sends that response. If the optional atomic boolean is present, it sets it to true and returns true; otherwise it returns false. Errors come back as JSON-RPC errors when the request is invalid.

Call relations: The client request handler calls this when it receives an initialize request. Inside, it asks the session whether it is already initialized, commits the initialized session state, calls login-client helpers to update process-wide identity, calls analytics to record the initialize event, and uses the outgoing message sender to reply to the exact connection and request. The boolean return tells the caller whether this function already marked outbound sending as initialized, which matters because some transports need to send connection-scoped notifications before opening the outbound path.

Call graph: calls 6 internal fn (track_initialize, initialize, initialized, get_codex_user_agent, set_default_client_residency_requirement, set_default_originator); called by 1 (handle_client_request); 5 external calls (from_str, new, clone, format!, warn!).

async fn send_initialize_notifications_to_connection(
        &self,
        connection_id: ConnectionId,
    )

Purpose: Sends any configuration warnings to one specific connection after initialization. This lets a newly connected client learn about startup configuration problems without broadcasting duplicates to everyone else.

Data flow: It receives a connection id and reads the stored list of configuration warning notifications. For each warning, it wraps the warning as a server notification and sends it only to the given connection through the outgoing message sender. It does not return data; its visible effect is sending messages.

Call relations: A higher-level initialization notification path calls this when only one connection should receive the warnings. This function does not decide what the warnings mean; it simply takes the warnings captured during configuration and hands them to the outgoing messaging layer for that connection.

Call graph: called by 1 (send_initialize_notifications_to_connection); 1 external calls (ConfigWarning).

async fn send_initialize_notifications(&self)

Purpose: Broadcasts any configuration warnings to all connected clients. This is useful when initialization-related warnings should be visible everywhere, not just to one newly connected client.

Data flow: It reads the processor's stored configuration warnings. For each warning, it turns it into a server notification and sends it through the outgoing message sender without limiting it to a single connection. It produces no direct return value; it sends notifications as its side effect.

Call relations: A higher-level notification path calls this when initialization warnings should be sent broadly. It relies on the outgoing messaging layer to perform the actual broadcast, while this function supplies the warning content in the expected server-notification form.

Call graph: called by 1 (send_initialize_notifications); 1 external calls (ConfigWarning).

fn track_initialized_request(
        &self,
        connection_id: ConnectionId,
        request_id: RequestId,
        request: &ClientRequest,
    )

Purpose: Records analytics for a normal client request after the connection has already been initialized. This gives the system visibility into what initialized clients are asking the server to do.

Data flow: It receives the connection id, request id, and the client request itself. It passes those details to the analytics events client, using the raw connection id value along with the request id and request content. It returns nothing; the outcome is an analytics record being submitted.

Call relations: The initialized request dispatcher calls this when it is about to process or has received a request from an initialized client. This function is a small bridge from request dispatching into the analytics system, keeping the analytics call in the same processor that owns initialization-related tracking.

Call graph: calls 1 internal fn (track_request); called by 1 (dispatch_initialized_client_request).

fn new(
        _origin: ConnectionOrigin,
        outbound_initialized: Arc<AtomicBool>,
        outbound_experimental_api_enabled: Arc<AtomicBool>,
        outbound_opted_out_notification_methods: A

Purpose: Creates the shared state for a newly connected client. It bundles together flags about outgoing capabilities with a fresh session record for that connection.

Data flow: It receives the connection’s origin and shared pieces of state, including whether outgoing messages are initialized, whether experimental API features are enabled, and which notifications the client opted out of. It stores those shared pieces and creates a new ConnectionSessionState, which is the per-client session memory. The result is a ConnectionState ready to be attached to the connection.

Call relations: This is used when a connection is being set up. It calls the session-state constructor so the connection starts with clean session data while still sharing capability flags with the outbound side of the same connection.

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

fn new(
        writer: mpsc::Sender<QueuedOutgoingMessage>,
        initialized: Arc<AtomicBool>,
        experimental_api_enabled: Arc<AtomicBool>,
        opted_out_notification_methods: Arc<RwLock

Purpose: Creates the sending-side record for a connection. This record tells the router how to send messages to that client and what limits or preferences apply.

Data flow: It receives a message sender, shared flags for initialization and experimental API support, the shared set of opted-out notification methods, and an optional cancellation token used for disconnecting. It stores these values unchanged. The output is an OutboundConnectionState that can later be used to queue outgoing messages or request a disconnect.

Call relations: This is called when outbound communication is prepared, including from setup code such as start_uninitialized and from tests that check broadcast behavior, experimental feature filtering, and notification opt-out behavior. Later, routing code reads the state it created to decide whether and how to send each message.

Call graph: called by 10 (start_uninitialized, broadcast_does_not_block_on_slow_connection, command_execution_request_approval_keeps_additional_permissions_with_capability, command_execution_request_approval_strips_additional_permissions_without_capability, experimental_notifications_are_dropped_without_capability, experimental_notifications_are_preserved_with_capability, to_connection_notification_respects_opt_out_filters, to_connection_notifications_are_dropped_for_opted_out_clients, to_connection_notifications_are_preserved_for_non_opted_out_clients, to_connection_stdio_waits_instead_of_disconnecting_when_writer_queue_is_full).

fn can_disconnect(&self) -> bool

Purpose: Answers whether this connection can be forcibly disconnected by this router. A connection can be disconnected only if it was given a cancellation token.

Data flow: It reads the optional disconnect token stored in the connection state. If the token exists, it returns true; otherwise it returns false. It does not change anything.

Call relations: This is used inside send_message_to_connection before choosing how to queue a message. If a connection can be disconnected, the router uses a non-blocking send and may drop the connection if its queue is full; otherwise it waits for space instead.

fn request_disconnect(&self)

Purpose: Asks the connection to shut down, if this connection supports that. It is the polite trigger used by the router when a client is gone or too slow.

Data flow: It looks for the optional cancellation token stored in the connection state. If one is present, it cancels that token, which signals the connection task to stop. It returns no value and does nothing when there is no token.

Call relations: This is called by disconnect_connection after the connection has been removed from the active map. It hands off the actual shutdown signal to the connection task through the cancellation token.

fn should_skip_notification_for_connection(
    connection_state: &OutboundConnectionState,
    message: &OutgoingMessage,
) -> bool

Purpose: Decides whether a notification should be withheld from a particular connection. It protects clients from receiving experimental messages they did not ask for and respects notification opt-out settings.

Data flow: It receives one connection’s outbound state and one outgoing message. It reads the connection’s opted-out notification set through a read lock, which is a shared-data guard that lets many readers look safely at the same data. If the lock cannot be read, it logs a warning and chooses not to skip the message. For app-server notifications, it checks whether the notification is experimental and whether the client enabled experimental APIs, then checks whether the notification method is in the opt-out set. It returns true when the message should be skipped and false otherwise.

Call relations: This helper is called by send_message_to_connection for direct sends and by route_outgoing_envelope when selecting broadcast targets. It acts as the gatekeeper before a notification is queued for a client.

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

fn disconnect_connection(
    connections: &mut HashMap<ConnectionId, OutboundConnectionState>,
    connection_id: ConnectionId,
) -> bool

Purpose: Removes a connection from the active outbound connection list and signals it to shut down. This keeps the server from continuing to send messages to a connection that should no longer be used.

Data flow: It receives the mutable map of active connections and the ID of the connection to remove. If that ID is present, it takes the connection state out of the map, asks it to disconnect, and returns true. If the ID is not present, it returns false and changes nothing.

Call relations: This is called by send_message_to_connection when a send fails, the outgoing channel is closed, or a disconnectable client’s queue is full. It is the cleanup step after the router decides a connection is no longer healthy.

Call graph: called by 1 (send_message_to_connection).

async fn send_message_to_connection(
    connections: &mut HashMap<ConnectionId, OutboundConnectionState>,
    connection_id: ConnectionId,
    message: OutgoingMessage,
    write_complete_tx: Option<

Purpose: Attempts to send one outgoing message to one specific connection. Before sending, it filters the message for that client’s capabilities and may skip it entirely if the client should not receive it.

Data flow: It receives the active connection map, a target connection ID, the outgoing message, and optionally a one-time completion sender used to report when writing is done. It looks up the connection; if missing, it logs that the message is being dropped. If present, it filters the message, checks notification skip rules, wraps the result into a queued message, and sends it through the connection’s writer channel. For disconnectable clients it tries to send immediately; if the queue is full or closed, it removes and disconnects the client. For non-disconnectable clients it waits for the send to complete and disconnects only if the channel has closed. It returns true when this call caused a disconnect and false otherwise.

Call relations: This is the worker used by route_outgoing_envelope for both direct messages and broadcasts. It calls filter_outgoing_message_for_connection to adapt the message, should_skip_notification_for_connection to respect capabilities and opt-outs, and disconnect_connection when sending is no longer possible.

Call graph: calls 3 internal fn (disconnect_connection, filter_outgoing_message_for_connection, should_skip_notification_for_connection); called by 1 (route_outgoing_envelope); 1 external calls (warn!).

fn filter_outgoing_message_for_connection(
    connection_state: &OutboundConnectionState,
    message: OutgoingMessage,
) -> OutgoingMessage

Purpose: Adjusts an outgoing message so it is safe for the receiving client’s supported feature set. In particular, it removes experimental request fields when the client has not enabled the experimental API.

Data flow: It receives a connection state and an outgoing message. It reads the connection’s experimental-API flag. If the message is a command-execution approval request and the client did not enable experimental features, it strips experimental fields from the request parameters and rebuilds the message. All other messages, or messages for clients with experimental support, pass through unchanged. The output is the message version that should be sent to that connection.

Call relations: This is called by send_message_to_connection before notification skipping and queuing. It ensures each client sees a message shape it understands, instead of forcing the rest of the server to know each client’s capabilities.

Call graph: called by 1 (send_message_to_connection); 1 external calls (Request).

async fn route_outgoing_envelope(
    connections: &mut HashMap<ConnectionId, OutboundConnectionState>,
    envelope: OutgoingEnvelope,
)

Purpose: Routes an outgoing envelope either to one named connection or to every suitable initialized connection. This is the main outward-facing routing function in the file.

Data flow: It receives the mutable map of active outbound connections and an OutgoingEnvelope, which is a wrapper that says where a message should go. For a direct envelope, it sends the message to the named connection and keeps any write-completion signal attached. For a broadcast envelope, it first builds a list of initialized connections that should receive the notification, excluding clients that are not ready or should skip it. It then sends a cloned copy of the message to each target connection without a write-completion signal.

Call relations: This is called by start_uninitialized, which is part of the wider server startup and connection loop. It delegates actual per-connection sending to send_message_to_connection, so the same filtering, opt-out checks, and slow-client disconnect behavior apply to both direct sends and broadcasts.

Call graph: calls 1 internal fn (send_message_to_connection); called by 1 (start_uninitialized).

fn server_notification_requires_delivery(notification: &ServerNotification) -> bool

Purpose: Decides whether a server notification is important enough that the in-process runtime should wait to deliver it instead of dropping it when the event queue is full. It protects terminal or state-changing messages, such as a turn completing, from being treated as disposable.

Data flow: It receives one server notification, checks which kind it is, and returns true for the few notification types that must be delivered. For all other notification types it returns false, meaning they may be skipped under pressure.

Call relations: When start_uninitialized is forwarding outgoing server messages to the embedded client, it asks this helper whether a notification needs guaranteed delivery. The answer decides whether the runtime waits for queue space or tries a non-blocking send that may fail if the client is behind.

Call graph: 1 external calls (matches!).

async fn request(&self, request: ClientRequest) -> IoResult<PendingClientRequestResponse>

Purpose: Sends a client request into the embedded app server and waits for the matching response. It is used when the caller expects either a successful JSON-RPC result or a JSON-RPC error.

Data flow: It takes a typed client request, creates a one-time reply channel, wraps both into an internal message, and tries to put that message on the runtime queue. Then it waits on the reply channel and returns the response, or an I/O-style error if the runtime disappears before answering.

Call relations: This is the lower-level sender used by InProcessClientHandle::request. It hands the request to try_send_client_message, and later receives the result that the runtime loop sends back after MessageProcessor produces a response.

Call graph: calls 1 internal fn (try_send_client_message); called by 1 (request); 2 external calls (new, channel).

fn notify(&self, notification: ClientNotification) -> IoResult<()>

Purpose: Sends a client notification into the embedded app server without waiting for a response. Notifications are fire-and-forget messages, such as telling the server that initialization is complete.

Data flow: It receives a typed notification, wraps it as an internal runtime message, and tries to place it on the client-to-runtime queue. It returns success if queued, or an I/O-style error if the queue is full or closed.

Call relations: This is called by InProcessClientHandle::notify. It uses try_send_client_message so notification sending follows the same backpressure and closed-runtime rules as requests.

Call graph: calls 1 internal fn (try_send_client_message); called by 1 (notify).

fn respond_to_server_request(&self, request_id: RequestId, result: Result) -> IoResult<()>

Purpose: Sends a successful answer to a request that originally came from the server. This is needed for flows where the app server asks the embedded client a question, such as an approval decision.

Data flow: It takes the server request ID and the result value, wraps them in an internal message, and tries to queue that message for the runtime. The function itself does not wait for the server to process the answer.

Call relations: This is called by InProcessClientHandle::respond_to_server_request. The runtime later forwards the answer to OutgoingMessageSender, which wakes the app-server side that is waiting for the client response.

Call graph: calls 1 internal fn (try_send_client_message); called by 1 (respond_to_server_request).

fn fail_server_request(
        &self,
        request_id: RequestId,
        error: JSONRPCErrorError,
    ) -> IoResult<()>

Purpose: Sends an error answer to a request that came from the server. Callers use it when they cannot or will not satisfy the server's request, so the server does not wait forever.

Data flow: It takes the server request ID and an error object, wraps them as an internal message, and attempts to put that message on the runtime queue. It returns only whether the message could be queued.

Call relations: This is called by InProcessClientHandle::fail_server_request. The runtime later passes the error into OutgoingMessageSender, which reports the failure back to the app-server logic waiting on that request.

Call graph: calls 1 internal fn (try_send_client_message); called by 1 (fail_server_request).

fn try_send_client_message(&self, message: InProcessClientMessage) -> IoResult<()>

Purpose: Performs the actual non-blocking send into the in-process runtime queue. It converts low-level queue problems into ordinary I/O-style errors that callers can understand.

Data flow: It receives an internal client message and tries to enqueue it immediately. If the queue accepts it, the result is success; if the queue is full, the result is WouldBlock; if the runtime has closed, the result is BrokenPipe.

Call relations: All sending methods on InProcessClientSender go through this helper. That keeps request, notification, and server-response behavior consistent when the embedded runtime is busy or already shut down.

Call graph: called by 4 (fail_server_request, notify, request, respond_to_server_request); 2 external calls (try_send, new).

async fn request(&self, request: ClientRequest) -> IoResult<PendingClientRequestResponse>

Purpose: Provides the public handle method for sending an app-server request and awaiting its response. This is the method most low-level in-process callers use when they want to ask the server to do something.

Data flow: It receives a typed client request from the caller and passes it to the inner InProcessClientSender. The returned value is either a transport error, or a JSON-RPC-level success or failure from the app server.

Call relations: This method delegates to InProcessClientSender::request. Other code, including thread-deletion flows noted in the call graph, calls this public handle method rather than talking to the sender directly.

Call graph: calls 1 internal fn (request); called by 1 (delete_thread).

fn notify(&self, notification: ClientNotification) -> IoResult<()>

Purpose: Provides the public handle method for sending a notification to the embedded app server. It is used for messages that do not have a reply.

Data flow: It takes a typed client notification and forwards it to the inner sender. The only output is whether the notification could be placed on the runtime queue.

Call relations: This is a thin public wrapper over InProcessClientSender::notify. start uses this path after a successful initialize request to send the required initialized notification.

Call graph: calls 1 internal fn (notify).

fn respond_to_server_request(&self, request_id: RequestId, result: Result) -> IoResult<()>

Purpose: Lets the embedded client answer a server request with a successful result. It keeps approval or question-and-answer flows moving after the caller receives a ServerRequest event.

Data flow: It takes a request ID and result, forwards them through the inner sender, and returns whether the answer was queued. The app-server state is changed later when the runtime processes that queued message.

Call relations: This method wraps InProcessClientSender::respond_to_server_request. It is meant to be used after next_event yields an InProcessServerEvent::ServerRequest.

Call graph: calls 1 internal fn (respond_to_server_request).

fn fail_server_request(
        &self,
        request_id: RequestId,
        error: JSONRPCErrorError,
    ) -> IoResult<()>

Purpose: Lets the embedded client reject or fail a server request. This is the safe alternative to ignoring a server request, which could leave the server waiting indefinitely.

Data flow: It takes a request ID and JSON-RPC error, forwards them to the inner sender, and returns whether the error response was queued. The runtime later sends the failure back to the app-server request waiter.

Call relations: This method wraps InProcessClientSender::fail_server_request. It belongs in the same event flow as respond_to_server_request, but is used when the client cannot provide a valid result.

Call graph: calls 1 internal fn (fail_server_request).

async fn next_event(&mut self) -> Option<InProcessServerEvent>

Purpose: Waits for the next event sent by the embedded app server to the in-process client. Events can be server requests, notifications, or a lag warning that tells the caller it fell behind.

Data flow: It waits on the event receiver queue. If an event is available, it returns that event; if the runtime has exited and the queue is drained, it returns None.

Call relations: Callers use this method while the runtime is active to consume messages produced by the routing loop in start_uninitialized. Server request events received here can be answered with respond_to_server_request or fail_server_request.

Call graph: calls 1 internal fn (recv).

async fn shutdown(self) -> IoResult<()>

Purpose: Requests a clean stop of the embedded app-server runtime and waits for its background tasks to finish. It prevents the local runtime from leaking work after the caller is done.

Data flow: It sends a shutdown message with a one-time acknowledgement channel, waits for that acknowledgement for a limited time, then waits for the runtime task itself. If the runtime does not finish in time, it aborts the task and still returns success from the shutdown attempt.

Call relations: This is the public teardown path for handles created by start or start_uninitialized. The runtime loop receives the shutdown message, drains and cancels outstanding work, stops processor and routing tasks, and then acknowledges shutdown.

Call graph: 2 external calls (channel, timeout).

fn sender(&self) -> InProcessClientSender

Purpose: Returns a cloneable sender that can be moved into other tasks while the main handle keeps receiving events. This is useful when one part of a caller sends commands and another part reads server events.

Data flow: It reads the handle's inner sender and returns a clone of it. The clone points to the same runtime queue, so messages sent through either sender go to the same embedded server.

Call relations: This helper exposes InProcessClientSender without giving away the event receiver or runtime task handle. It supports multi-task caller designs built on top of the same in-process runtime.

Call graph: 1 external calls (clone).

async fn start(args: InProcessStartArgs) -> IoResult<InProcessClientHandle>

Purpose: Starts the embedded app server and performs the required initialization handshake before returning control to the caller. Callers get a handle that is already ready to use.

Data flow: It takes all startup arguments, saves the initialize parameters, starts the lower-level runtime with start_uninitialized, sends an Initialize request, checks whether that succeeded, then sends the Initialized notification. If initialization fails, it shuts the runtime down and returns an invalid-data error.

Call relations: This is the normal entry into this file's functionality and is used by higher-level in-process clients and tests. It relies on start_uninitialized for the task setup, then uses the public request and notification path to make startup match the normal app-server protocol.

Call graph: calls 1 internal fn (start_uninitialized); called by 9 (start, start_test_client_with_capacity, get_conversation_summary_by_thread_id_reads_pathless_store_thread, mcp_resource_read_returns_error_for_unknown_thread, start_in_process_client, thread_list_includes_store_thread_without_rollout_path, thread_read_loaded_include_turns_reads_store_history_without_rollout_path, thread_turns_list_reads_store_history_without_rollout_path, thread_unarchive_preserves_pathless_store_metadata); 3 external calls (Integer, new, format!).

async fn start_uninitialized(args: InProcessStartArgs) -> IoResult<InProcessClientHandle>

Purpose: Builds and launches the in-process app-server runtime but does not perform the initialize handshake itself. It sets up the queues, background tasks, message processor, outbound routing, and shutdown cleanup.

Data flow: It receives startup configuration, clamps the queue capacity to at least one, resolves the installation ID, creates client and event queues, and spawns the runtime task. Inside that task, client messages are forwarded into MessageProcessor, outgoing responses are matched back to waiting requests, server events are sent to the client, and shutdown cancels outstanding work and drains background tasks.

Call relations: start calls this first, then performs initialization on top of the returned handle. This function is the central wiring point: it connects the in-memory client queue, the existing MessageProcessor, the outgoing-envelope router, and the event stream seen by next_event.

Call graph: calls 9 internal fn (analytics_events_client_from_config, new, internal_error, new, new, new, new, route_outgoing_envelope, shared_from_config); called by 1 (start); 11 external calls (clone, new, new, new, new, new, new, resolve_installation_id, select!, spawn (+1 more)).

async fn build_test_config(codex_home: &Path) -> Config

Purpose: Builds a configuration object for tests using a temporary Codex home directory. It falls back to the default config-loading path if the builder path cannot produce a config.

Data flow: It receives a filesystem path, tries to build a Config using that path, and returns the resulting config. If the first build attempt fails, it loads the default config with no command-line overrides for the same directory.

Call relations: The test startup helper calls this before creating an in-process runtime. It keeps the tests focused on runtime behavior instead of repeating config setup in every test.

Call graph: 4 external calls (to_path_buf, new, load_default_with_cli_overrides_for_codex_home, default).

async fn start_test_client_with_capacity(
        session_source: SessionSource,
        channel_capacity: usize,
    ) -> InProcessClientHandle

Purpose: Creates a fully initialized in-process client for tests, with a caller-chosen queue capacity. It packages all the many startup dependencies into safe test defaults.

Data flow: It creates a temporary Codex home, builds config, initializes test state storage, fills an InProcessStartArgs struct, calls start, stores the temp directory on the handle so it lives long enough, and returns the ready client.

Call relations: Most tests in this module call this helper directly or through tests::start_test_client. It exercises the same public start path used outside tests, while supplying test-only environment and configuration pieces.

Call graph: calls 5 internal fn (start, default, default_for_tests, new, try_init); 6 external calls (new, new, new, build_test_config, default, default).

async fn start_test_client(session_source: SessionSource) -> InProcessClientHandle

Purpose: Starts a test in-process client using the default queue capacity. It is a convenience wrapper for tests that do not care about queue sizing.

Data flow: It receives the desired session source, passes it along with DEFAULT_IN_PROCESS_CHANNEL_CAPACITY to tests::start_test_client_with_capacity, and returns the initialized client.

Call relations: The request and session-source tests call this helper. It keeps those tests short while still using the fuller setup path underneath.

Call graph: 1 external calls (start_test_client_with_capacity).

async fn in_process_start_initializes_and_handles_typed_v2_request()

Purpose: Checks that start returns a runtime that has already completed initialization and can answer a typed protocol request. It verifies the basic promise of this file: ready-to-use in-process app-server access.

Data flow: The test starts a client, sends a ConfigRequirementsRead request, confirms the transport succeeded and the app-server request succeeded, parses the returned JSON into the expected response type, and then shuts the client down.

Call relations: This test uses tests::start_test_client, then calls the same public request and shutdown methods a real embedded caller would use. It protects the startup handshake and request-response path from regressions.

Call graph: 4 external calls (Integer, start_test_client, assert!, from_value).

async fn in_process_start_uses_requested_session_source_for_thread_start()

Purpose: Checks that the session source supplied at startup is preserved when a new thread is created. This matters because callers such as CLI and exec surfaces need their sessions labeled correctly.

Data flow: For each requested source, the test starts a client, sends a thread-start request, parses the response, and compares the created thread's source to the expected API value. It then shuts down that client before trying the next case.

Call relations: This test uses tests::start_test_client and the public request path. It confirms that startup data passed through InProcessStartArgs reaches the MessageProcessor and appears in app-server results.

Call graph: 5 external calls (Integer, default, start_test_client, assert_eq!, from_value).

async fn in_process_start_clamps_zero_channel_capacity()

Purpose: Checks that asking for a zero-sized runtime queue does not break startup. The runtime should clamp the capacity to at least one and still process requests.

Data flow: The test starts a client with capacity zero, repeatedly tries a config request until it is accepted if the queue is briefly full, verifies the response parses correctly, and then shuts down the client.

Call relations: This test calls tests::start_test_client_with_capacity, which reaches start_uninitialized where the capacity is clamped. It protects callers from accidental invalid queue configuration.

Call graph: 5 external calls (Integer, start_test_client_with_capacity, panic!, from_value, yield_now).

fn guaranteed_delivery_helpers_cover_terminal_server_notifications()

Purpose: Checks that the helper for guaranteed notification delivery includes important terminal notifications. It makes sure completion-style messages are not accidentally treated as droppable.

Data flow: The test builds sample TurnCompleted and ExternalAgentConfigImportCompleted notifications, passes each to server_notification_requires_delivery, and asserts that the helper returns true.

Call relations: This directly tests server_notification_requires_delivery, which is used by the event-forwarding path in start_uninitialized. It guards the policy that important end-of-flow notifications should survive queue pressure.

Call graph: 1 external calls (assert!).

fn status_code(&self) -> StatusCode

Purpose: Returns the HTTP status code attached to an authentication failure. Callers use it to decide what response code to send back to the client.

Data flow: It reads the stored status code inside the error object and gives that code back unchanged. It does not change anything.

Call relations: When websocket authorization fails, other code can call this accessor to turn the internal error into an HTTP response.

fn message(&self) -> &'static str

Purpose: Returns the short error message attached to an authentication failure. This lets the response-building code explain why access was denied.

Data flow: It reads the stored message inside the error object and returns that static text. Nothing else is modified.

Call relations: It pairs with WebsocketAuthError::status_code so callers can produce both the HTTP code and the human-readable reason.

fn try_into_settings(self) -> anyhow::Result<AppServerWebsocketAuthSettings>

Purpose: Turns raw command-line websocket authentication flags into a validated settings object. It catches mismatched options early, before the server starts listening.

Data flow: It receives the parsed command-line fields, trims optional issuer and audience text, checks which authentication mode was requested, and rejects flags that do not belong to that mode. It converts path arguments into absolute paths and parses a hex SHA-256 token digest when needed, then returns either clean settings or a clear error.

Call relations: This is the first step in the authentication setup story. It uses absolute_path_arg and sha256_digest_arg for detailed validation, and it stops startup with an error when the user gives an impossible or unsafe combination of flags.

Call graph: calls 2 internal fn (absolute_path_arg, sha256_digest_arg); 1 external calls (bail!).

fn policy_from_settings(
    settings: &AppServerWebsocketAuthSettings,
) -> io::Result<WebsocketAuthPolicy>

Purpose: Builds the runtime websocket authentication policy from already-validated settings. This is where startup settings become the actual rule used later on incoming websocket requests.

Data flow: It receives an AppServerWebsocketAuthSettings value. If capability-token mode uses a file, it reads and trims the token, hashes it, and stores only the hash; if the hash was supplied directly, it stores that. If signed-token mode is used, it reads the shared secret file, checks that the secret is long enough, converts the clock-skew setting into the right number type, and stores all of that in a WebsocketAuthPolicy. If no auth was configured, it returns a policy with no mode.

Call relations: The main server startup path calls this after command-line settings are prepared. Later, websocket request code uses the returned policy in authorize_upgrade, and listener setup can use it to warn or block unsafe unauthenticated non-local listeners.

Call graph: calls 3 internal fn (read_trimmed_secret, sha256_digest, validate_signed_bearer_secret); called by 2 (capability_token_hash_policy_authorizes_matching_bearer_token, run_main_with_transport_options); 1 external calls (try_from).

fn is_unauthenticated_non_loopback_listener(
    bind_address: SocketAddr,
    policy: &WebsocketAuthPolicy,
) -> bool

Purpose: Checks whether the server is about to listen on a non-local network address without websocket authentication. This helps catch a dangerous setup before exposing access to other machines.

Data flow: It receives a socket address and an authentication policy. It checks whether the IP address is not loopback, meaning not just this same computer, and whether the policy has no authentication mode. It returns true only when both are true.

Call relations: The websocket acceptor setup calls this while deciding whether a listener is safe. It does not authenticate a request itself; it flags risky listener configuration.

Call graph: called by 1 (start_websocket_acceptor); 1 external calls (ip).

fn authorize_upgrade(
    headers: &HeaderMap,
    policy: &WebsocketAuthPolicy,
) -> Result<(), WebsocketAuthError>

Purpose: Decides whether a websocket upgrade request is allowed under the current authentication policy. This is the main request-time gate.

Data flow: It receives HTTP headers and the current policy. If no authentication is configured, it allows the request. Otherwise it extracts a bearer token from the Authorization header. For capability-token mode, it hashes the presented token and compares it with the stored hash. For signed-token mode, it verifies the JWT using the shared secret and claim rules. It returns success or a WebsocketAuthError.

Call relations: The websocket upgrade handler calls this before accepting a connection. It relies on bearer_token_from_headers to read the client’s credential, sha256_digest and constant-time comparison for simple tokens, and verify_signed_bearer_token for signed JWTs.

Call graph: calls 4 internal fn (bearer_token_from_headers, sha256_digest, unauthorized, verify_signed_bearer_token); called by 2 (capability_token_hash_policy_authorizes_matching_bearer_token, websocket_upgrade_handler); 1 external calls (constant_time_eq_32).

fn verify_signed_bearer_token(
    token: &str,
    shared_secret: &[u8],
    issuer: Option<&str>,
    audience: Option<&str>,
    max_clock_skew_seconds: i64,
) -> Result<(), WebsocketAuthError>

Purpose: Checks that a signed bearer token is genuine and acceptable for this server. A bearer token is a credential the client presents in an HTTP Authorization header.

Data flow: It receives the token string, shared secret bytes, optional expected issuer and audience, and allowed clock skew. It first decodes and verifies the JWT signature, then checks the decoded claims such as expiry and audience. It returns success if every check passes, otherwise an authentication error.

Call relations: authorize_upgrade calls this in signed-bearer-token mode. The tests also call it directly to confirm that valid tokens pass and tampered or incomplete tokens fail.

Call graph: calls 2 internal fn (decode_jwt_claims, validate_jwt_claims); called by 6 (authorize_upgrade, signed_bearer_token_verification_accepts_multiple_audiences, signed_bearer_token_verification_accepts_valid_token, signed_bearer_token_verification_rejects_alg_none_tokens, signed_bearer_token_verification_rejects_missing_exp, signed_bearer_token_verification_rejects_tampering).

fn decode_jwt_claims(token: &str, shared_secret: &[u8]) -> Result<JwtClaims, WebsocketAuthError>

Purpose: Verifies the JWT signature and extracts the claims, which are the token’s stated facts such as expiry time and audience.

Data flow: It receives the token text and the shared secret. It configures JWT decoding to use HS256, a shared-secret signing method, and asks the JWT library to verify the signature while leaving claim checks to this file. It returns the decoded claims or an Unauthorized error if decoding or signature verification fails.

Call relations: verify_signed_bearer_token calls this first, before validate_jwt_claims checks the meaning of the decoded data.

Call graph: called by 1 (verify_signed_bearer_token); 2 external calls (from_secret, new).

fn validate_jwt_claims(
    claims: &JwtClaims,
    issuer: Option<&str>,
    audience: Option<&str>,
    max_clock_skew_seconds: i64,
) -> Result<(), WebsocketAuthError>

Purpose: Checks whether decoded JWT claims are still valid for this server right now. It enforces expiry, optional start time, issuer, and audience rules.

Data flow: It receives decoded claims, optional expected issuer and audience, and a clock-skew allowance. It compares the current UTC time with the token’s expiry and not-before times, then compares issuer and audience when configured. It returns success if the token is acceptable, or an Unauthorized error with a specific reason if not.

Call relations: verify_signed_bearer_token calls this after decode_jwt_claims succeeds. It delegates audience comparison to audience_matches because JWTs can store one audience or a list of audiences.

Call graph: calls 2 internal fn (audience_matches, unauthorized); called by 1 (verify_signed_bearer_token); 1 external calls (now_utc).

fn audience_matches(audience: Option<&JwtAudienceClaim>, expected_audience: &str) -> bool

Purpose: Checks whether a JWT audience claim contains the audience this server expects. The audience is like a “this token is meant for” label.

Data flow: It receives an optional audience claim and the expected audience string. If the token has a single audience, it compares that one value. If it has a list, it searches the list. If there is no audience claim, it returns false.

Call relations: validate_jwt_claims calls this only when the server was configured to require a specific audience.

Call graph: called by 1 (validate_jwt_claims).

fn bearer_token_from_headers(headers: &HeaderMap) -> Result<&str, WebsocketAuthError>

Purpose: Extracts the token from an HTTP Authorization header in the expected Bearer <token> format. It rejects missing, malformed, non-text, or empty credentials.

Data flow: It receives the request headers, looks for the Authorization header, converts it to text, splits it into an authentication scheme and token, checks that the scheme is Bearer, trims the token, and returns the token text. On any problem, it returns an Unauthorized error.

Call relations: authorize_upgrade calls this before it can check either kind of websocket authentication credential.

Call graph: calls 1 internal fn (unauthorized); called by 1 (authorize_upgrade); 1 external calls (get).

fn validate_signed_bearer_secret(path: &Path, shared_secret: &[u8]) -> io::Result<()>

Purpose: Makes sure the shared secret used to sign JWTs is not too short. A short secret would be easier to guess, so the server refuses it at startup.

Data flow: It receives the secret file path and the secret bytes read from that file. It checks that the secret is at least 32 bytes long. It returns success for a strong-enough secret, or an invalid-input error that names the file when it is too short.

Call relations: policy_from_settings calls this while building signed-bearer-token policy. A test also calls it directly to confirm short secrets are rejected.

Call graph: called by 2 (policy_from_settings, validate_signed_bearer_secret_rejects_short_secret); 2 external calls (new, format!).

fn read_trimmed_secret(path: &std::path::Path) -> io::Result<String>

Purpose: Reads a secret value from a file and removes surrounding whitespace. This lets secret files end with a newline without making the newline part of the secret.

Data flow: It receives a file path, reads the file as text, trims whitespace from the beginning and end, and checks that something remains. It returns the trimmed secret string, or an I/O error with context if the file cannot be read or is empty.

Call relations: policy_from_settings calls this when a token or shared secret is supplied through a file.

Call graph: called by 1 (policy_from_settings); 3 external calls (new, format!, read_to_string).

fn absolute_path_arg(flag_name: &str, path: PathBuf) -> anyhow::Result<AbsolutePathBuf>

Purpose: Checks that a path supplied on the command line is absolute, meaning it starts from the filesystem root rather than depending on the current directory.

Data flow: It receives the flag name and a path. It tries to convert the path into an AbsolutePathBuf and, if that fails, returns an error that mentions which flag was wrong.

Call relations: AppServerWebsocketAuthArgs::try_into_settings calls this for token and shared-secret file arguments so later startup code has unambiguous file locations.

Call graph: calls 1 internal fn (try_from); called by 1 (try_into_settings).

fn sha256_digest_arg(flag_name: &str, value: &str) -> anyhow::Result<[u8; 32]>

Purpose: Parses a command-line SHA-256 digest written as 64 hexadecimal characters. Hexadecimal is a compact text form for bytes using digits 0-9 and letters a-f.

Data flow: It receives the flag name and text value, trims the value, checks that it has exactly 64 characters, converts each pair of hex characters into one byte, and returns the resulting 32-byte digest. If the shape or characters are wrong, it returns a clear argument error.

Call relations: AppServerWebsocketAuthArgs::try_into_settings calls this when capability-token mode is configured with a precomputed token hash. It uses hex_nibble for the per-character conversion.

Call graph: calls 1 internal fn (hex_nibble); called by 1 (try_into_settings); 1 external calls (bail!).

fn hex_nibble(flag_name: &str, byte: u8) -> anyhow::Result<u8>

Purpose: Converts one hexadecimal character into its 4-bit numeric value. It is a small helper for reading SHA-256 digests from command-line text.

Data flow: It receives the flag name and one byte representing a character. If the character is 0-9, a-f, or A-F, it returns the corresponding number from 0 to 15. Otherwise it returns the same digest-format error used by the parser.

Call relations: sha256_digest_arg calls this twice for each byte of the final SHA-256 digest.

Call graph: called by 1 (sha256_digest_arg); 1 external calls (bail!).

fn sha256_digest(input: &[u8]) -> [u8; 32]

Purpose: Computes the SHA-256 fingerprint of some bytes and returns it as exactly 32 bytes. This is used to compare secrets without keeping or comparing the plain secret directly.

Data flow: It receives a byte slice, runs the SHA-256 hash function over it, copies the result into a fixed 32-byte array, and returns that array. It does not modify the input.

Call relations: policy_from_settings uses this to store a capability token as a hash, authorize_upgrade uses it to hash a presented token before comparison, and tests use it to create expected hashes.

Call graph: called by 3 (authorize_upgrade, policy_from_settings, capability_token_hash_policy_authorizes_matching_bearer_token); 1 external calls (digest).

fn unauthorized(message: &'static str) -> WebsocketAuthError

Purpose: Creates a standard websocket authentication error with HTTP 401 Unauthorized. It keeps error creation consistent across the file.

Data flow: It receives a static message, combines it with the Unauthorized HTTP status code, and returns a WebsocketAuthError.

Call relations: authorize_upgrade, bearer_token_from_headers, and validate_jwt_claims call this whenever a request should be rejected for authentication reasons.

Call graph: called by 3 (authorize_upgrade, bearer_token_from_headers, validate_jwt_claims).

fn signed_token(shared_secret: &[u8], claims: serde_json::Value) -> String

Purpose: Builds a test JWT signed with HS256 so the tests can exercise real signature verification. It is only used in the test module.

Data flow: It receives shared secret bytes and JSON claims. It base64-url encodes a JWT header and the claims, signs the header-and-claims text with HMAC-SHA256, base64-url encodes the signature, and returns the full token string.

Call relations: Several signed-bearer-token tests call this to create valid or intentionally modified tokens for verify_signed_bearer_token.

Call graph: 3 external calls (new_from_slice, format!, to_vec).

fn detects_unauthenticated_non_loopback_listener()

Purpose: Checks that the server can spot an unauthenticated listener exposed beyond the local machine. This protects against accidentally opening an unsecured websocket port to the network.

Data flow: It creates a default no-auth policy, tests a public-style address and a loopback address, then tests a public-style address with authentication configured. The expected results confirm that only non-loopback plus no-auth is flagged.

Call relations: This test directly exercises is_unauthenticated_non_loopback_listener, the helper used during websocket listener setup.

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

fn capability_token_args_require_token_file_or_hash()

Purpose: Confirms that capability-token mode cannot be enabled without telling the server what token or token hash to expect.

Data flow: It builds command-line args with capability-token mode but no token source, converts them to settings, and expects an error mentioning the missing token file or hash option.

Call relations: This test exercises AppServerWebsocketAuthArgs::try_into_settings and verifies one of its startup configuration guardrails.

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

fn capability_token_args_accept_token_hash()

Purpose: Confirms that a valid SHA-256 token hash supplied on the command line is accepted and decoded correctly.

Data flow: It builds args with capability-token mode and a 64-character hex digest, converts them to settings, and compares the result with the expected 32-byte hash value.

Call relations: This test covers the path from AppServerWebsocketAuthArgs::try_into_settings through sha256_digest_arg and hex_nibble.

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

fn capability_token_args_reject_multiple_token_sources()

Purpose: Confirms that the user cannot provide both a token file and a token hash for capability-token mode. Having two sources would be ambiguous.

Data flow: It builds args containing both token-source options, converts them to settings, and expects an error saying the options are mutually exclusive.

Call relations: This test exercises the configuration validation inside AppServerWebsocketAuthArgs::try_into_settings.

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

fn capability_token_args_reject_malformed_token_hash()

Purpose: Confirms that an invalid token hash string is rejected before startup continues.

Data flow: It builds args with capability-token mode and a non-SHA-256-looking string, tries to convert them to settings, and expects an error about the required 64-character hex form.

Call relations: This test checks AppServerWebsocketAuthArgs::try_into_settings through sha256_digest_arg.

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

fn capability_token_hash_policy_authorizes_matching_bearer_token()

Purpose: Confirms that capability-token authentication accepts the correct bearer token and rejects a wrong one.

Data flow: It creates settings containing the hash of a known token, builds a policy, sends headers with the matching token and expects success, then replaces the header with a wrong token and expects Unauthorized.

Call relations: This test follows the real flow from policy_from_settings to authorize_upgrade, with sha256_digest used to prepare the expected hash.

Call graph: calls 3 internal fn (authorize_upgrade, policy_from_settings, sha256_digest); 3 external calls (new, from_static, assert_eq!).

fn signed_bearer_args_require_mode_when_mode_specific_flags_are_set()

Purpose: Confirms that signed-token-specific flags are not accepted unless the user explicitly chooses a websocket auth mode.

Data flow: It builds args with a shared secret file but no --ws-auth mode, converts them to settings, and expects an error telling the user to choose a mode.

Call relations: This test exercises AppServerWebsocketAuthArgs::try_into_settings and its rule that mode-specific options must not float on their own.

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

fn signed_bearer_args_default_clock_skew_and_trim_optional_claims()

Purpose: Confirms that signed-bearer-token settings get sensible cleanup: default clock skew, trimmed issuer text, and empty audience treated as absent.

Data flow: It builds signed-token args with a secret file, an issuer surrounded by spaces, and a blank audience. After conversion, it compares the settings with the expected absolute path, trimmed issuer, no audience, and default clock-skew value.

Call relations: This test focuses on AppServerWebsocketAuthArgs::try_into_settings and its normalization of signed-bearer-token options.

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

fn signed_bearer_token_verification_rejects_tampering()

Purpose: Confirms that changing a signed JWT after it was created makes verification fail. This proves the signature check is actually protecting the token contents.

Data flow: It creates a valid signed token, alters part of the token text, then calls verify_signed_bearer_token and expects an Unauthorized error.

Call relations: This test uses tests::signed_token to create the starting token and then checks verify_signed_bearer_token directly.

Call graph: calls 1 internal fn (verify_signed_bearer_token); 3 external calls (signed_token, assert_eq!, json!).

fn signed_bearer_token_verification_accepts_valid_token()

Purpose: Confirms that a properly signed, unexpired JWT with the expected issuer and audience is accepted.

Data flow: It creates a token with a future expiry, issuer, and audience, then verifies it with matching expected values. The expected result is success.

Call relations: This test uses tests::signed_token and calls verify_signed_bearer_token, covering both signature decoding and claim validation.

Call graph: calls 1 internal fn (verify_signed_bearer_token); 2 external calls (signed_token, json!).

fn signed_bearer_token_verification_accepts_multiple_audiences()

Purpose: Confirms that a JWT audience list is accepted when one entry matches the expected audience.

Data flow: It creates a signed token whose audience claim is an array containing both an unrelated value and the expected value, then verifies it. The expected result is success.

Call relations: This test checks verify_signed_bearer_token and, through it, the audience_matches helper for list-style audience claims.

Call graph: calls 1 internal fn (verify_signed_bearer_token); 2 external calls (signed_token, json!).

fn signed_bearer_token_verification_rejects_alg_none_tokens()

Purpose: Confirms that unsigned JWTs claiming alg: none are rejected. This protects against a classic JWT mistake where a server accepts tokens with no real signature.

Data flow: It manually builds a token with an alg value of none and no signature, then asks verify_signed_bearer_token to check it. The expected result is an Unauthorized error.

Call relations: This test targets the decode_jwt_claims part of verify_signed_bearer_token, ensuring the decoder only accepts the configured HS256 signed-token method.

Call graph: calls 1 internal fn (verify_signed_bearer_token); 4 external calls (assert_eq!, format!, json!, to_vec).

fn signed_bearer_token_verification_rejects_missing_exp()

Purpose: Confirms that a JWT without an expiry claim is rejected. Tokens need an expiry so stolen credentials do not remain useful forever.

Data flow: It creates a signed token that has an issuer but no exp expiry field, then verifies it and expects an Unauthorized error.

Call relations: This test calls verify_signed_bearer_token with a token built by tests::signed_token, checking that decoding into required claims fails when expiry is absent.

Call graph: calls 1 internal fn (verify_signed_bearer_token); 3 external calls (signed_token, assert_eq!, json!).

fn validate_signed_bearer_secret_rejects_short_secret()

Purpose: Confirms that too-short shared secrets are refused. This keeps signed-token security from depending on weak, easy-to-guess secrets.

Data flow: It calls validate_signed_bearer_secret with a short byte string and expects an invalid-input error whose message says the secret must be at least 32 bytes.

Call relations: This test directly exercises validate_signed_bearer_secret, the startup check used by policy_from_settings.

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

async fn start_stdio_connection(
    transport_event_tx: mpsc::Sender<TransportEvent>,
    stdio_handles: &mut Vec<JoinHandle<()>>,
    initialize_client_name_tx: oneshot::Sender<String>,
) -> IoResul

Purpose: Starts a stdin/stdout-based connection for the app server. It announces the new connection to the rest of the system, then launches one background reader for incoming lines and one background writer for outgoing messages.

Data flow: It receives a channel for sending transport events, a list where it can store background task handles, and a one-time sender for reporting the initializing client’s name. It creates a new connection id and an internal outgoing-message channel, sends a “connection opened” event, then starts reading stdin and writing stdout in separate tasks. Incoming text lines become transport events for the server; outgoing queued messages become newline-ended JSON on stdout. It returns success if setup worked, or an input/output error if the transport event receiver is unavailable.

Call relations: This is the entry point for stdio transport setup. While reading each stdin line, it calls stdio_initialize_client_name to see whether the line is the initial handshake and, if so, extracts the client name. It also hands incoming lines to the shared transport helper that forwards messages into the server, and hands outgoing messages to the shared serializer before writing them to stdout.

Call graph: calls 1 internal fn (stdio_initialize_client_name); 13 external calls (new, clone, send, take, debug!, error!, info!, stdin, stdout, forward_incoming_message (+3 more)).

fn stdio_initialize_client_name(line: &str) -> Option<String>

Purpose: Looks at one incoming line and tries to pull out the client program’s name from an “initialize” request. This lets the server learn who is connecting during the startup handshake.

Data flow: It takes a single text line, tries to parse it as a JSON-RPC message, checks that it is a request whose method is exactly “initialize”, then parses its parameters as initialization data. If all of that succeeds, it returns the client name. If the line is not valid JSON, is not a request, is for another method, or lacks usable parameters, it returns nothing.

Call relations: This helper is used by start_stdio_connection inside the stdin reading loop. The reader calls it for each incoming line until it successfully sends the client name through the one-time notification channel; after that, the name sender is no longer used, but normal message forwarding continues.

Call graph: called by 1 (start_stdio_connection).

async fn start_control_socket_acceptor(
    socket_path: AbsolutePathBuf,
    transport_event_tx: mpsc::Sender<TransportEvent>,
    shutdown_token: CancellationToken,
) -> IoResult<JoinHandle<()>>

Purpose: Starts the local control socket listener. It prepares the socket path, opens the Unix socket, makes its permissions private, and launches the background task that accepts clients.

Data flow: It receives an absolute socket path, a channel for sending transport events, and a shutdown token. It first checks and prepares the path, binds a listener to that path, wraps the path in a cleanup guard, sets file permissions, logs that the socket is ready, and returns a task handle for the newly spawned accept loop. If preparation or binding fails, it returns an I/O error instead.

Call relations: This is the setup doorway for the file. It calls prepare_control_socket_path before binding, calls set_control_socket_permissions after the socket file exists, and then starts run_control_socket_acceptor in a Tokio task so accepting connections can continue in the background.

Call graph: calls 5 internal fn (prepare_control_socket_path, run_control_socket_acceptor, set_control_socket_permissions, bind, as_path); 2 external calls (info!, spawn).

async fn run_control_socket_acceptor(
    mut listener: UnixListener,
    transport_event_tx: mpsc::Sender<TransportEvent>,
    shutdown_token: CancellationToken,
    socket_guard: ControlSocketFileGu

Purpose: Runs the ongoing accept loop for the control socket. It waits for local clients, upgrades each connection to WebSocket, and passes it into the shared WebSocket connection runner.

Data flow: It receives a Unix socket listener, a sender for transport events, a shutdown token, and a socket-file cleanup guard. While the shutdown token is not cancelled, it waits for new socket connections. Recoverable accept errors are logged and retried; other accept errors are logged and followed by a short pause before retrying. For each successful connection, it spawns a new task, performs the WebSocket upgrade, splits the connection into reading and writing halves, and hands those halves plus the event sender to run_websocket_connection. When shutdown is requested, the loop exits and the cleanup guard later removes the socket file.

Call relations: start_control_socket_acceptor creates this task after the socket is ready. This function is the bridge between low-level Unix socket accepting and the higher-level WebSocket transport: once a client connects, it hands the connection off to run_websocket_connection.

Call graph: calls 1 internal fn (run_websocket_connection); called by 1 (start_control_socket_acceptor); 6 external calls (clone, info!, select!, spawn, accept_async, warn!).

async fn prepare_control_socket_path(socket_path: &Path) -> IoResult<()>

Purpose: Makes sure the socket path is safe and usable before the server tries to listen on it. It prevents accidentally starting a second server on the same socket and clears away stale socket files left by old runs.

Data flow: It receives a filesystem path. If the path has a parent directory, it prepares that directory as a private socket directory. Then it tries to connect to the path. If a connection succeeds, another server is already listening, so it returns an “address in use” error. If the path does not exist, it succeeds. If the path refuses connections, it checks whether the file is a stale socket; if so, it removes it. If the path exists but is not a stale socket, it returns an error rather than deleting something unexpected.

Call relations: start_control_socket_acceptor calls this before binding the listener. It relies on helper functions from codex_uds to prepare private directories and recognize stale socket files, so the later bind step starts from a clean and safe filesystem state.

Call graph: calls 1 internal fn (connect); called by 1 (start_control_socket_acceptor); 8 external calls (exists, parent, try_exists, new, is_stale_socket_path, prepare_private_socket_directory, format!, remove_file).

async fn acquire_app_server_startup_lock(
    startup_lock_path: AbsolutePathBuf,
) -> IoResult<AppServerStartupLock>

Purpose: Takes a startup lock so only one app server startup path can proceed at a time. This avoids two processes both thinking they are responsible for creating or owning the control socket.

Data flow: It receives an absolute path for a lock file. It prepares the parent directory if needed, then runs blocking file-lock work on a separate blocking thread so it does not stall the async runtime. That work opens or creates the lock file, locks it, and returns an AppServerStartupLock that keeps the file open. Holding that returned object keeps the lock alive; dropping it releases the lock.

Call relations: This helper is not called by the other functions in this file according to the provided graph, but it supports the same startup story. It complements the socket preparation code by reducing races before the socket acceptor is started.

Call graph: calls 1 internal fn (as_path); 2 external calls (prepare_private_socket_directory, spawn_blocking).

async fn set_control_socket_permissions(_socket_path: &Path) -> IoResult<()>

Purpose: Restricts who can access the control socket file. On Unix systems it sets the socket file to owner-only access, which helps keep local control traffic private.

Data flow: It receives the socket path. On Unix, it converts the private mode value into filesystem permissions and applies them to the socket file. On non-Unix platforms, the matching version does nothing and succeeds, because Unix permission bits do not apply there in the same way.

Call relations: start_control_socket_acceptor calls this right after binding the listener, once the socket file exists. It is a security step between creating the socket and announcing that the app-server control socket is listening.

Call graph: called by 1 (start_control_socket_acceptor); 2 external calls (from_mode, set_permissions).

fn drop(&mut self)

Purpose: Cleans up the socket file when the guard is dropped. This helps prevent stale socket files from being left behind after the acceptor stops.

Data flow: It reads the stored socket path from the guard and tries to remove that file from disk. If the file is already gone, it ignores that. If removal fails for another reason, it logs a warning with the socket path and the error.

Call relations: start_control_socket_acceptor creates the guard and passes it into run_control_socket_acceptor. That acceptor keeps the guard alive for as long as it is listening; when the acceptor exits during shutdown or task cleanup, this drop method runs and removes the socket file.

Call graph: calls 1 internal fn (as_path); 2 external calls (remove_file, warn!).

fn colorize(text: &str, style: Style) -> String

Purpose: Adds terminal color and style to a short piece of text when the user’s terminal supports it. This is only for making the startup banner easier to read.

Data flow: It receives plain text and a style, such as bold or green. It asks the color library to apply that style only when stderr supports color, then returns the final string to print.

Call relations: The startup banner uses this helper each time it wants a label or URL to look distinct. It does not take part in networking; it only prepares display text for print_websocket_startup_banner.

Call graph: called by 1 (print_websocket_startup_banner).

fn print_websocket_startup_banner(addr: SocketAddr)

Purpose: Prints a human-friendly startup message showing where the WebSocket server is listening and where its health checks live. It also gives a safety note about localhost versus non-localhost access.

Data flow: It receives the bound socket address. It formats WebSocket and HTTP URLs from that address, colorizes the pieces, and writes several lines to stderr. Nothing is returned.

Call relations: start_websocket_acceptor calls this after the operating system has successfully assigned a listening address. It relies on colorize to make the banner readable, then hands no data onward.

Call graph: calls 1 internal fn (colorize); called by 1 (start_websocket_acceptor); 4 external calls (ip, new, eprintln!, format!).

async fn health_check_handler() -> StatusCode

Purpose: Replies to health-check requests with a simple “OK” HTTP status. This lets other tools ask whether the listener process is alive.

Data flow: It takes no meaningful input from the request body. It returns HTTP 200 OK, with no extra calculation or state change.

Call relations: start_websocket_acceptor wires this into the /readyz and /healthz routes. Monitoring or startup-check clients call those routes to confirm that the listener is reachable.

async fn reject_requests_with_origin_header(
    request: Request<Body>,
    next: Next,
) -> Result<Response, StatusCode>

Purpose: Blocks requests that include an Origin header. This is a safety guard against browser-style cross-site requests being silently upgraded into trusted WebSocket connections.

Data flow: It receives an HTTP request and the next router step. If the request headers include Origin, it logs a warning and returns HTTP 403 Forbidden. If not, it passes the request to the next step and returns that response.

Call relations: start_websocket_acceptor installs this as middleware, meaning it runs before the health routes or WebSocket upgrade route. When it allows a request through, Axum continues to whichever handler matches next.

Call graph: 3 external calls (run, headers, warn!).

async fn websocket_upgrade_handler(
    websocket: WebSocketUpgrade,
    ConnectInfo(peer_addr): ConnectInfo<SocketAddr>,
    State(state): State<WebSocketListenerState>,
    headers: HeaderMap,
) ->

Purpose: Decides whether an incoming HTTP request may become a WebSocket connection, then starts the per-connection WebSocket work if it is allowed.

Data flow: It receives the pending WebSocket upgrade, the client’s socket address, shared listener state, and request headers. It checks the headers against the configured authentication policy. On failure, it returns an error HTTP response; on success, it accepts the upgrade and starts a connection task using the WebSocket stream.

Call relations: The router created by start_websocket_acceptor sends fallback requests here. It calls the authentication helper before accepting the client. After upgrade, it splits the WebSocket into read and write halves and hands them to run_websocket_connection.

Call graph: calls 1 internal fn (authorize_upgrade); 3 external calls (on_upgrade, info!, warn!).

async fn start_websocket_acceptor(
    bind_address: SocketAddr,
    transport_event_tx: mpsc::Sender<TransportEvent>,
    shutdown_token: CancellationToken,
    auth_policy: WebsocketAuthPolicy,
) ->

Purpose: Starts the WebSocket server listener and returns the background task that keeps it running. This is the main setup point for WebSocket transport.

Data flow: It receives a bind address, a channel for sending transport events into the rest of the app, a shutdown token, and an authentication policy. It refuses unsafe unauthenticated public listeners, binds the TCP socket, prints the banner, builds the router, and spawns the Axum server. It returns either an I/O error or a handle to the spawned server task.

Call relations: Higher-level startup code calls this when WebSocket transport should be enabled. It wires together health_check_handler, reject_requests_with_origin_header, websocket_upgrade_handler, and the shared listener state. The spawned server watches the shutdown token so it can stop gracefully.

Call graph: calls 2 internal fn (is_unauthenticated_non_loopback_listener, print_websocket_startup_banner); 13 external calls (new, cancelled, new, bind, any, get, serve, new, error!, format! (+3 more)).

async fn run_websocket_connection(
    websocket_writer: impl futures::sink::Sink<M, Error = SinkError> + Send + 'static,
    websocket_reader: impl futures::stream::Stream<Item = Result<M, StreamErro

Purpose: Runs one accepted WebSocket client connection until either reading or writing ends. It announces connection open and close events to the rest of the app.

Data flow: It receives a WebSocket writer, a WebSocket reader, and the app’s transport event channel. It creates a new connection ID, creates channels for outgoing messages and control replies, sends a ConnectionOpened event, then starts separate inbound and outbound loops. When either loop ends, it cancels the other and sends a ConnectionClosed event.

Call relations: websocket_upgrade_handler uses this after a successful WebSocket upgrade, and the provided call graph also shows it being reused by run_control_socket_acceptor. It starts run_websocket_outbound_loop for server-to-client traffic and run_websocket_inbound_loop for client-to-server traffic, tying both to the same cancellation token.

Call graph: calls 2 internal fn (run_websocket_inbound_loop, run_websocket_outbound_loop); called by 1 (run_control_socket_acceptor); 6 external calls (new, clone, send, next_connection_id, select!, spawn).

fn text(text: String) -> Self

Purpose: Builds an Axum WebSocket text message from a string. The outbound loop uses this shape when it needs to send JSON text through an Axum WebSocket.

Data flow: It receives a string. It wraps that string in Axum’s WebSocket text-message type and returns it.

Call relations: run_websocket_outbound_loop calls this through the AppServerWebSocketMessage trait when the concrete WebSocket type is Axum’s message type. This keeps the outbound loop generic instead of tied to one WebSocket library.

Call graph: 1 external calls (Text).

fn pong(payload: Bytes) -> Self

Purpose: Builds an Axum WebSocket pong reply. A pong is the standard answer to a ping, showing the connection is still alive.

Data flow: It receives the ping payload bytes. It wraps those bytes in Axum’s pong-message type and returns it.

Call relations: run_websocket_inbound_loop asks for this through the AppServerWebSocketMessage trait when it receives a ping. The returned message is sent through the control queue to the outbound loop.

Call graph: 1 external calls (Pong).

fn into_incoming(self) -> Option<IncomingWebSocketMessage>

Purpose: Converts Axum’s detailed WebSocket message type into the smaller set of message kinds this transport cares about. This lets the rest of the file work with one simple internal WebSocket vocabulary.

Data flow: It receives one Axum WebSocket message. It classifies it as text, binary, ping, pong, or close, preserving text content and ping bytes where needed. It returns that simpler classification.

Call relations: run_websocket_inbound_loop uses this through the AppServerWebSocketMessage trait before deciding what to do with a received frame. Text is forwarded inward, ping gets a pong reply, close stops the connection, and binary is ignored with a warning.

Call graph: 2 external calls (Ping, Text).

fn text(text: String) -> Self

Purpose: Builds a Tungstenite WebSocket text message from a string. Tungstenite is another Rust WebSocket library used by this transport path.

Data flow: It receives a string. It wraps that string in Tungstenite’s text-message type and returns it.

Call relations: run_websocket_outbound_loop can call this through the AppServerWebSocketMessage trait when the connection uses Tungstenite messages. This is part of the adapter layer that lets the same loop work with more than one WebSocket implementation.

Call graph: 1 external calls (Text).

fn pong(payload: Bytes) -> Self

Purpose: Builds a Tungstenite WebSocket pong reply for a received ping. This keeps the connection compliant with normal WebSocket keepalive behavior.

Data flow: It receives the ping payload bytes. It wraps those bytes in Tungstenite’s pong-message type and returns it.

Call relations: run_websocket_inbound_loop requests this through the AppServerWebSocketMessage trait after seeing a ping. The pong is then passed to the outbound loop through the control channel.

Call graph: 1 external calls (Pong).

fn into_incoming(self) -> Option<IncomingWebSocketMessage>

Purpose: Converts Tungstenite’s WebSocket message type into the simple internal message categories used by this transport. It ignores raw protocol frame objects because the transport does not need to process them directly.

Data flow: It receives one Tungstenite WebSocket message. It turns normal text, binary, ping, pong, and close messages into the shared IncomingWebSocketMessage form. If the message is a low-level frame, it returns nothing.

Call relations: run_websocket_inbound_loop uses this through the AppServerWebSocketMessage trait. This lets the inbound loop make the same decisions for Tungstenite connections as it does for Axum connections.

Call graph: 2 external calls (Ping, Text).

async fn run_websocket_outbound_loop(
    websocket_writer: impl futures::sink::Sink<M, Error = SinkError> + Send + 'static,
    mut writer_rx: mpsc::Receiver<QueuedOutgoingMessage>,
    mut writer_co

Purpose: Continuously writes messages from the app out to the WebSocket client. It is the server-to-client half of a live WebSocket connection.

Data flow: It receives a WebSocket writer, a channel of queued outgoing app messages, a channel of immediate control messages such as pongs, and a disconnect token. It waits for whichever event comes first: shutdown, a control message, or an app message. App messages are serialized to JSON text before sending. If sending fails or a channel closes, the loop exits.

Call relations: run_websocket_connection starts this as a background task for each client. It receives normal outbound messages from the connection’s writer channel and control replies from run_websocket_inbound_loop. When it finishes, run_websocket_connection cancels the inbound loop and closes the connection.

Call graph: called by 1 (run_websocket_connection); 2 external calls (pin!, select!).

async fn run_websocket_inbound_loop(
    websocket_reader: impl futures::stream::Stream<Item = Result<M, StreamError>> + Send + 'static,
    transport_event_tx: mpsc::Sender<TransportEvent>,
    write

Purpose: Continuously reads messages arriving from the WebSocket client. It is the client-to-server half of a live WebSocket connection.

Data flow: It receives a WebSocket reader, the app’s transport event channel, a writer channel tied to this client, a control-message channel, the connection ID, and a disconnect token. For text messages, it forwards the content into the app’s transport system. For pings, it queues a pong reply. For close, read errors, full control queues, or shutdown, it exits. Unsupported binary messages are logged and dropped.

Call relations: run_websocket_connection starts this beside run_websocket_outbound_loop. It calls the shared forwarding path for valid text messages and uses the outbound loop’s control channel for pong replies. When it finishes, run_websocket_connection cancels the outbound loop and reports the connection closed.

Call graph: called by 1 (run_websocket_connection); 2 external calls (pin!, select!).

fn take_remote_control_disabled_env() -> bool

Purpose: Checks whether an internal environment variable says remote control should start disabled, then removes that marker. This is used at process startup so the setting is consumed once before worker threads begin.

Data flow: It reads the process environment for CODEX_INTERNAL_APP_SERVER_REMOTE_CONTROL_DISABLED. If the value is exactly 1, it returns true; otherwise it returns false. In either case, it removes the environment variable afterward.

Call relations: This is an early startup helper. It relies only on standard environment-variable calls and does not hand work to the rest of the remote-control machinery directly.

Call graph: 2 external calls (remove_var, var_os).

fn new(enrollment: Option<RemoteControlEnrollment>) -> Self

Purpose: Creates the shared container that remembers the current remote-control server enrollment. It also creates a one-at-a-time lock so pairing and websocket setup cannot edit that enrollment at the same time.

Data flow: It takes an optional existing enrollment. It stores that enrollment in a protected slot and creates a semaphore, which is a small gate that allows only one holder through.

Call relations: Startup uses this when building the remote-control system. Tests and helper setup code also use it to create controlled enrollment state.

Call graph: called by 5 (start_remote_control, client_management_handle, plain_start_resolves_persisted_remote_control_preference, remote_control_handle_with_current_enrollment, test_current_enrollment); 2 external calls (new, new).

async fn lock(&self) -> RemoteControlEnrollmentLease<'_>

Purpose: Takes exclusive access to the current enrollment and returns a temporary lease for editing it. The lease is like checking out a document from a cabinet: while you hold it, no one else edits the original.

Data flow: It waits for the semaphore permit, copies the current enrollment snapshot, and returns a RemoteControlEnrollmentLease containing that copy. When the lease is later dropped, its final value is written back.

Call relations: Pairing flows call this before loading, refreshing, or replacing enrollment information. It calls snapshot to get the starting value.

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

fn snapshot(&self) -> Option<RemoteControlEnrollment>

Purpose: Makes a safe copy of the current enrollment without taking the longer async lease. This gives callers a quick read of what server enrollment is currently selected.

Data flow: It locks the internal standard mutex, clones the optional enrollment, and returns that clone. The stored enrollment remains in place.

Call relations: It is used by RemoteControlEnrollmentState::lock to initialize the editable lease.

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

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

Purpose: Lets the enrollment lease be read as if it were the optional enrollment it contains. This makes the lease convenient to pass into code that expects normal enrollment data.

Data flow: It receives the lease by reference and returns a read-only reference to the enrollment copy inside it. Nothing is changed.

Call relations: This supports the lock-and-edit pattern used by pairing and enrollment code.

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

Purpose: Lets the enrollment lease be edited as if it were the optional enrollment it contains. This is how callers update the checked-out enrollment copy.

Data flow: It receives the lease by mutable reference and returns a mutable reference to its internal enrollment copy. Changes affect the lease copy until it is dropped.

Call relations: This works with RemoteControlEnrollmentLease::drop, which writes the edited copy back to shared state.

fn drop(&mut self)

Purpose: Writes the lease’s final enrollment value back into the shared enrollment state when the lease goes out of scope. This is the automatic “return the document to the cabinet” step.

Data flow: It takes the enrollment value from the lease, locks the shared storage, and replaces the stored enrollment with that value.

Call relations: It completes the flow started by RemoteControlEnrollmentState::lock. Callers do not call it manually; Rust runs it automatically when the lease is finished.

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

Purpose: Provides the human-readable message for the error used when remote control cannot work because the local SQLite state database is unavailable. SQLite is the small local database used for saved state.

Data flow: It receives a formatter and writes a fixed explanatory sentence into it. The result is used wherever the error is displayed.

Call relations: This supports RemoteControlEnableError and other user-facing error paths that need a clear reason.

Call graph: 1 external calls (write!).

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

Purpose: Provides the human-readable message for the error used when policy or managed requirements forbid remote control. This makes the failure reason explicit instead of looking like a random connection problem.

Data flow: It receives a formatter and writes a fixed message saying remote control is disabled by managed requirements.

Call relations: This is used when policy checks in RemoteControlHandle reject an operation.

Call graph: 1 external calls (write!).

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

Purpose: Turns the broader enable-error enum into the right human-readable message. It delegates to the specific error inside it.

Data flow: It receives either an unavailable-state error or a disabled-by-policy error. It formats whichever one is present and returns the formatting result.

Call relations: This is used by callers of enable operations when they need to display or log why enabling remote control failed.

fn ensure_remote_control_allowed(&self) -> Result<(), RemoteControlDisabledByRequirements>

Purpose: Checks whether remote control is allowed by the current policy. It stops operations early when managed requirements have disabled the feature.

Data flow: It reads the handle’s policy. If the policy is Allowed, it returns success; if the policy is DisabledByRequirements, it returns a specific policy error.

Call relations: Enable and I/O-style permission checks call this before doing work. It is the main gatekeeper for policy enforcement.

Call graph: called by 2 (enable_with_preference, ensure_remote_control_allowed_io).

fn ensure_remote_control_allowed_io(&self) -> io::Result<()>

Purpose: Runs the same policy check as ensure_remote_control_allowed, but converts the result into an io::Result. That lets network-style and database-style functions report the policy failure in their normal error format.

Data flow: It calls ensure_remote_control_allowed. Success stays success; a disabled-by-policy error becomes a permission-denied I/O error.

Call relations: Disable, pairing, client listing, and client revocation call this before they talk to storage or remote services.

Call graph: calls 1 internal fn (ensure_remote_control_allowed); called by 5 (disable, list_clients, pairing_status, revoke_client, start_pairing).

fn enable_ephemeral(
        &self,
    ) -> Result<RemoteControlStatusChangedNotification, RemoteControlEnableError>

Purpose: Requests remote control to be enabled without explicitly saving that preference as a permanent user setting. “Ephemeral” here means the request is for the current run unless existing state says otherwise.

Data flow: It passes no persistence preference into enable_with_preference. The result is the latest remote-control status notification or an enable error.

Call relations: This is the simple public enable method. It hands the real decision-making to enable_with_preference.

Call graph: calls 1 internal fn (enable_with_preference).

fn enable_with_preference(
        &self,
        persistence_preference: Option<bool>,
    ) -> Result<RemoteControlStatusChangedNotification, RemoteControlEnableError>

Purpose: Changes the desired state to enabled and publishes a connecting status if needed. It also refuses to enable remote control when policy forbids it or when the local state database is missing.

Data flow: It reads policy, database availability, the current desired state, and the current status. It updates the desired-state watch channel to enabled, possibly preserving a previous persistence preference, then returns the current status if already connecting/connected or publishes Connecting.

Call relations: Called by enable_ephemeral. It calls ensure_remote_control_allowed, status, and publish_status; the background websocket task observes the desired-state change and does the actual connection work.

Call graph: calls 3 internal fn (ensure_remote_control_allowed, publish_status, status); called by 1 (enable_ephemeral); 4 external calls (Unavailable, info!, matches!, warn!).

async fn disable(
        &self,
        app_server_client_name: Option<&str>,
    ) -> io::Result<RemoteControlStatusChangedNotification>

Purpose: Turns remote control off and saves that disabled preference when possible. This is the persistent disable path used when the choice should be remembered.

Data flow: It checks policy, takes locks so only one desired-state change and persistence write happen at a time, writes the disabled preference to the state database, then moves the in-memory state to disabled and returns the new status.

Call relations: It calls persist_preference before transition_disabled. The locks coordinate with other remote-control state changes and with websocket persistence work.

Call graph: calls 4 internal fn (ensure_remote_control_allowed_io, persist_preference, transition_disabled, acquire_persistence_lock).

async fn disable_ephemeral(&self) -> RemoteControlStatusChangedNotification

Purpose: Turns remote control off for the current run without saving that as a persistent preference. This is useful for temporary shutdowns or internal mode changes.

Data flow: It takes the same state-change locks as the persistent disable path, skips the database write, changes the desired state to disabled, and returns the new status notification.

Call relations: It calls transition_disabled after taking the persistence lock. Unlike disable, it does not call persist_preference.

Call graph: calls 2 internal fn (transition_disabled, acquire_persistence_lock).

fn transition_disabled(&self) -> RemoteControlStatusChangedNotification

Purpose: Performs the in-memory transition to disabled and publishes a disabled connection status. This is the shared final step for both persistent and temporary disabling.

Data flow: It updates the desired-state watch channel to Disabled, reads the current status for logging, publishes a Disabled status, and returns that status notification.

Call relations: Called by disable and disable_ephemeral. It uses publish_status so status subscribers hear about the change.

Call graph: calls 2 internal fn (publish_status, status); called by 2 (disable, disable_ephemeral); 1 external calls (info!).

async fn persist_preference(
        &self,
        app_server_client_name: Option<&str>,
        remote_control_enabled: bool,
    ) -> io::Result<()>

Purpose: Saves whether remote control should be enabled for this app server, account, and remote-control service target. This is how the choice survives restart.

Data flow: It reads the state database, current remote-control authentication, the normalized remote-control URL, and the pairing persistence key. It writes the enabled/disabled preference into the database and returns success or an I/O error.

Call relations: Called by disable. It depends on authentication loading, URL normalization, and pairing_persistence_key to identify the right saved row.

Call graph: calls 3 internal fn (pairing_persistence_key, load_remote_control_auth, normalize_remote_control_url); called by 1 (disable).

fn status(&self) -> RemoteControlStatusChangedNotification

Purpose: Returns the latest known remote-control status. This is a quick snapshot for callers that want to know whether the feature is disabled, connecting, or connected.

Data flow: It reads the current value from the status watch channel, clones it, and returns the clone. It does not change state.

Call relations: Enable, disable, pairing, and status publishing code call this when they need the latest status object.

Call graph: called by 5 (enable_with_preference, pairing_status, publish_status, start_pairing, transition_disabled).

fn status_receiver(&self) -> watch::Receiver<RemoteControlStatusChangedNotification>

Purpose: Gives callers a subscription to future remote-control status changes. This is useful for UI or protocol code that wants to be notified instead of polling repeatedly.

Data flow: It creates a new receiver subscribed to the status watch channel. The caller receives the current status immediately and later updates as they happen.

Call relations: This exposes the status stream maintained by publish_status and the websocket status publisher.

async fn start_pairing(
        &self,
        params: RemoteControlPairingStartParams,
        app_server_client_name: Option<&str>,
    ) -> io::Result<RemoteControlPairingStartResponse>

Purpose: Starts the process of pairing a new remote-control client with this app server. It ensures remote control is enabled, finds or creates the server enrollment, refreshes expired credentials when needed, and asks the remote service to begin pairing.

Data flow: It takes pairing parameters and an optional app-server client name. It loads auth, reads current status, locks enrollment state, loads or creates enrollment, refreshes tokens if needed, sends a start-pairing request, checks that the account and enabled state did not change mid-flight, then returns the pairing response.

Call relations: This is called by request-handling code when a user starts pairing. It calls load_or_enroll_pairing_server, refresh_pairing_enrollment, clear_pairing_server_token, and several validation helpers to recover from stale or rejected server credentials.

Call graph: calls 8 internal fn (ensure_remote_control_allowed_io, load_or_enroll_pairing_server, pairing_persistence_key, status, load_remote_control_auth, clear_pairing_server_token, pairing_unavailable_error, refresh_pairing_enrollment); 2 external calls (lock, pairing_disabled_error).

async fn load_or_enroll_pairing_server(
        &self,
        current_enrollment: &mut Option<RemoteControlEnrollment>,
        auth: &mut auth::RemoteControlConnectionAuth,
        installation_id:

Purpose: Gets a usable server enrollment for pairing and, if it had to create a new one, saves it to local state. Enrollment is the server’s registration with the remote-control service.

Data flow: It receives the current enrollment slot, auth, installation/server identity, optional client name, and a reuse-or-replace choice. It loads or creates an enrollment, saves newly created enrollment details with the current persistence preference, publishes it into shared state, and returns it.

Call relations: Called by start_pairing and pairing_status when they need a valid enrollment. It builds on load_or_enroll_server and updates persistence through update_persisted_remote_control_enrollment.

Call graph: calls 4 internal fn (load_or_enroll_server, acquire_persistence_lock, update_persisted_remote_control_enrollment, publish_current_enrollment); called by 2 (pairing_status, start_pairing); 1 external calls (pairing_disabled_error).

async fn load_or_enroll_server(
        &self,
        current_enrollment: &Option<RemoteControlEnrollment>,
        auth: &mut auth::RemoteControlConnectionAuth,
        installation_id: &str,

Purpose: Chooses the actual enrollment record to use. It reuses the current one when safe, loads a saved one from the database when available, or creates a new enrollment with the remote service.

Data flow: It normalizes the remote-control URL, checks whether the current enrollment belongs to the current account, optionally loads a persisted enrollment, or calls enroll_pairing_server to create one. It returns the enrollment plus a flag saying whether it was newly created.

Call relations: Called only by load_or_enroll_pairing_server. It is the lower-level selection step before persistence and publication happen.

Call graph: calls 3 internal fn (load_persisted_remote_control_enrollment, enroll_pairing_server, normalize_remote_control_url); called by 1 (load_or_enroll_pairing_server).

fn pairing_persistence_key(
        &self,
        app_server_client_name: Option<&str>,
    ) -> io::Result<Option<String>>

Purpose: Finds or establishes the client-name key used to store pairing-related preferences. This matters when multiple app-server clients might need separate saved remote-control settings.

Data flow: It checks whether a persistence key is required and missing. If so, it uses the provided app-server client name, stores it in a watch channel, and returns the current key as an optional string.

Call relations: Called by persist_preference and start_pairing. It supplies the identifying key used for database persistence.

Call graph: called by 2 (persist_preference, start_pairing); 2 external calls (borrow, send_replace).

async fn pairing_status(
        &self,
        params: RemoteControlPairingStatusParams,
    ) -> io::Result<RemoteControlPairingStatusResponse>

Purpose: Asks the remote service whether a pairing attempt has completed, failed, or is still pending. It also refreshes credentials and protects against account or enabled-state changes during the check.

Data flow: It takes status-query parameters, validates that remote control is allowed and enabled, loads auth, locks current enrollment, refreshes the enrollment token if needed, converts the request’s pairing code into the internal form, asks the remote service for status, handles stale or unauthorized enrollment errors, and returns the response.

Call relations: Request-handling code calls this after start_pairing. It uses remote_control_pairing_status_code, refresh_pairing_enrollment, clear_pairing_server_token, and may call load_or_enroll_pairing_server if the remote service says the saved enrollment no longer exists.

Call graph: calls 8 internal fn (ensure_remote_control_allowed_io, load_or_enroll_pairing_server, status, load_remote_control_auth, clear_pairing_server_token, pairing_unavailable_error, refresh_pairing_enrollment, remote_control_pairing_status_code); 3 external calls (lock, borrow, pairing_disabled_error).

async fn list_clients(
        &self,
        params: RemoteControlClientsListParams,
    ) -> io::Result<RemoteControlClientsListResponse>

Purpose: Lists clients that are authorized to use remote control for this account/service. This lets users inspect who can connect.

Data flow: It receives list parameters, checks policy, then passes the remote-control URL, auth manager, and parameters to the client-management module. It returns the list response or an I/O error.

Call relations: This is a public handle method used by request-handling code. It delegates the service call to clients::list_remote_control_clients.

Call graph: calls 2 internal fn (ensure_remote_control_allowed_io, list_remote_control_clients).

async fn revoke_client(
        &self,
        params: RemoteControlClientsRevokeParams,
    ) -> io::Result<RemoteControlClientsRevokeResponse>

Purpose: Revokes a remote-control client so it can no longer connect. This is the safety valve for removing access.

Data flow: It receives revoke parameters, checks policy, then passes the remote-control URL, auth manager, and parameters to the client-management module. It returns the revoke response or an I/O error.

Call relations: This is a public handle method used by request-handling code. It delegates the service call to clients::revoke_remote_control_client.

Call graph: calls 2 internal fn (ensure_remote_control_allowed_io, revoke_remote_control_client).

fn pairing_disabled_error() -> io::Error

Purpose: Creates the standard error used when someone tries to pair while remote control is not enabled. This keeps the message consistent across pairing paths.

Data flow: It creates an invalid-input I/O error with a fixed explanatory message and returns it.

Call relations: Pairing setup code uses this when the desired state is disabled or no longer enabled.

Call graph: 1 external calls (new).

fn publish_status(
        &self,
        connection_status: RemoteControlConnectionStatus,
    ) -> RemoteControlStatusChangedNotification

Purpose: Updates the shared remote-control status and notifies subscribers if the connection status actually changed. It avoids sending duplicate status updates.

Data flow: It receives a new connection status, combines it with the existing server name and installation details, updates the status watch channel only if the full status changed, logs the transition, and returns the latest status.

Call relations: Called by enable and disable transitions. The returned status is what API callers can send back to clients, while subscribers receive the same update through the watch channel.

Call graph: calls 1 internal fn (status); called by 2 (enable_with_preference, transition_disabled); 1 external calls (info!).

async fn enroll_pairing_server(
    auth_manager: &Arc<AuthManager>,
    auth: &mut auth::RemoteControlConnectionAuth,
    remote_control_target: &protocol::RemoteControlTarget,
    installation_id: &

Purpose: Registers this app server with the remote-control service for pairing. If the first attempt fails because authentication is no longer valid, it tries to recover auth and then retries once.

Data flow: It receives the auth manager, mutable auth data, remote-control target, installation ID, and server name. It attempts enrollment; on permission failure, it asks the auth manager to recover, reloads auth, and tries enrollment again. It returns the new enrollment or an error.

Call relations: Called by RemoteControlHandle::load_or_enroll_server when no usable existing enrollment is available. It delegates the actual service call to enroll_remote_control_server.

Call graph: calls 3 internal fn (load_remote_control_auth, recover_remote_control_auth, enroll_remote_control_server); called by 1 (load_or_enroll_server).

fn remote_control_pairing_status_code(
    params: &RemoteControlPairingStatusParams,
) -> io::Result<RemoteControlPairingStatusCode>

Purpose: Validates the pairing-status request and turns its code field into the internal form used by the protocol layer. It enforces that the caller provides exactly one kind of pairing code.

Data flow: It reads pairing_code and manual_pairing_code from the parameters. If exactly one is present, it wraps that value in the matching internal enum; if both or neither are present, it returns an invalid-input error.

Call relations: Called by RemoteControlHandle::pairing_status before contacting the remote service.

Call graph: called by 1 (pairing_status); 3 external calls (ManualPairingCode, PairingCode, new).

async fn refresh_pairing_enrollment(
    current_enrollment: &mut Option<RemoteControlEnrollment>,
    auth_manager: &Arc<AuthManager>,
    auth: &mut auth::RemoteControlConnectionAuth,
    installati

Purpose: Refreshes the server token inside an enrollment when it is expired or rejected. The server token is the credential used to prove this app server is registered.

Data flow: It tries to refresh the enrollment using current auth. If permission is denied, it attempts auth recovery, reloads auth, verifies the account still matches, and retries. If refresh succeeds and the enrollment still matches the current selected server, it writes the refreshed enrollment back.

Call relations: Called by start_pairing and pairing_status when an enrollment says its server token should be refreshed or when the remote service rejects a request. It uses replace_current_enrollment to avoid overwriting a different selected enrollment.

Call graph: calls 5 internal fn (load_remote_control_auth, recover_remote_control_auth, refresh_remote_control_server, pairing_unavailable_error, replace_current_enrollment); called by 2 (pairing_status, start_pairing).

fn clear_pairing_server_token(
    current_enrollment: &mut Option<RemoteControlEnrollment>,
    enrollment: &mut RemoteControlEnrollment,
) -> io::Result<()>

Purpose: Removes the server token from an enrollment after the remote service rejects it. This prevents the code from continuing to trust a credential that is known to be bad.

Data flow: It clears the token in the given enrollment, then tries to replace the current shared enrollment with that token-cleared version. It returns success if the shared enrollment still matches, otherwise a pairing-unavailable error.

Call relations: Called by start_pairing and pairing_status after permission-denied responses. It uses replace_current_enrollment for safe shared-state update.

Call graph: calls 3 internal fn (clear_server_token, pairing_unavailable_error, replace_current_enrollment); called by 2 (pairing_status, start_pairing).

fn pairing_unavailable_error() -> io::Error

Purpose: Creates the standard error used when pairing cannot proceed because enrollment is not ready or no longer valid. This gives callers a consistent explanation.

Data flow: It creates an invalid-input I/O error with a fixed message and returns it.

Call relations: Used throughout pairing flows, especially by start_pairing, pairing_status, refresh_pairing_enrollment, and clear_pairing_server_token.

Call graph: called by 4 (pairing_status, start_pairing, clear_pairing_server_token, refresh_pairing_enrollment); 1 external calls (new).

fn remote_control_status_with_connection_status(
    status: &RemoteControlStatusChangedNotification,
    connection_status: RemoteControlConnectionStatus,
) -> RemoteControlStatusChangedNotification

Purpose: Builds a new status notification by changing only the connection status while preserving identity fields. If remote control becomes disabled, it also clears the environment ID because there is no active remote environment.

Data flow: It takes the current status and a new connection status. It copies server name and installation ID, sets the new status, and either keeps or clears the environment ID depending on whether the status is disabled.

Call relations: Used by RemoteControlHandle::publish_status to create the next status value consistently.

fn publish_current_enrollment(
    current_enrollment: &mut Option<RemoteControlEnrollment>,
    enrollment: &RemoteControlEnrollment,
)

Purpose: Stores a selected enrollment as the current shared enrollment. This makes later pairing or websocket work use the same server registration.

Data flow: It takes a mutable current-enrollment slot and an enrollment reference. It clones the enrollment and puts it into the slot.

Call relations: Called by load_or_enroll_pairing_server after an enrollment has been reused or newly saved.

Call graph: called by 1 (load_or_enroll_pairing_server); 1 external calls (clone).

fn replace_current_enrollment(
    current_enrollment: &mut Option<RemoteControlEnrollment>,
    enrollment: &RemoteControlEnrollment,
) -> bool

Purpose: Safely replaces the current enrollment only if it is still the same enrollment record. This prevents one async operation from overwriting another operation’s newer choice.

Data flow: It compares the current stored enrollment with the proposed updated enrollment by account, server, and environment. If they match, it stores the clone and returns true; otherwise it leaves state unchanged and returns false.

Call relations: Called by refresh_pairing_enrollment and clear_pairing_server_token after changing token-related fields.

Call graph: called by 2 (clear_pairing_server_token, refresh_pairing_enrollment); 1 external calls (clone).

fn same_remote_control_enrollment(
    left: &RemoteControlEnrollment,
    right: &RemoteControlEnrollment,
) -> bool

Purpose: Checks whether two enrollment objects refer to the same remote server registration. It deliberately ignores rotating token values, because tokens can change while the underlying enrollment stays the same.

Data flow: It compares account ID, server ID, and environment ID. If all three match, it returns true; otherwise it returns false.

Call relations: Used by replace_current_enrollment as the safety check before writing refreshed or token-cleared enrollment data.

async fn start_remote_control(
    config: RemoteControlStartConfig,
    state_db: Option<Arc<StateRuntime>>,
    auth_manager: Arc<AuthManager>,
    transport_event_tx: mpsc::Sender<TransportEvent>,

Purpose: Sets up the whole remote-control subsystem and starts its background websocket task. It returns both the spawned task and a handle that other code can use to control remote control.

Data flow: It takes startup configuration, optional state database, auth manager, event sender, shutdown token, optional client-name receiver, and startup mode. It decides the initial desired state, prepares watch channels, locks, enrollment state, status state, and websocket configuration, spawns the websocket task, and returns the task handle plus RemoteControlHandle.

Call relations: This is the main entry point for this module during app-server startup. It creates RemoteControlWebsocket, hands it channels and shared state, and wraps the public control methods in RemoteControlHandle for the rest of the server.

Call graph: calls 4 internal fn (new, normalize_remote_control_url, new, new); 11 external calls (new, clone, new, error!, gethostname, info!, AssertUnwindSafe, resume_unwind, spawn, warn! (+1 more)).

fn is_enabled(self) -> bool

Purpose: This answers the simple question: does this desired-state value mean remote control is enabled? It hides the enum details so other code can ask for a plain yes-or-no result.

Data flow: It takes one RemoteControlDesiredState value. If the value is Enabled, regardless of its saved-preference detail, it returns true; otherwise it returns false. It does not change anything.

Call relations: This is a small helper used when code has already resolved or read the desired state and needs a boolean answer. In this file, RemoteControlHandle::resolve_persisted_preference uses it after checking that the state is no longer unknown.

Call graph: 1 external calls (matches!).

async fn acquire_persistence_lock(lock: &Semaphore) -> SemaphorePermit<'_>

Purpose: This waits for the lock that protects saved remote-control state. It is used so only one task at a time can change the persisted enrollment or enabled flag.

Data flow: It receives a semaphore, which is a one-at-a-time gate. It waits until a permit is available, then returns that permit. While the permit is held, other tasks trying to take the same lock must wait.

Call relations: Several remote-control state transitions call this before touching persisted state: disable, disable_ephemeral, load_or_enroll_pairing_server, enable, enroll_and_persist_remote_control_server, and resolve_desired_state_after_account_change. In this file, RemoteControlHandle::enable uses it just before writing the enabled preference to the database.

Call graph: called by 6 (disable, disable_ephemeral, load_or_enroll_pairing_server, enable, enroll_and_persist_remote_control_server, resolve_desired_state_after_account_change); 1 external calls (acquire).

fn desired_state_from_persisted_enrollment(
    enrollment: Option<RemoteControlEnrollmentRecord>,
) -> RemoteControlDesiredState

Purpose: This converts a saved enrollment record into the app’s in-memory desired-state value. It treats only an explicit saved true as enabled; anything missing, unset, or false becomes disabled.

Data flow: It receives an optional saved enrollment record. If the record exists and its remote_control_enabled field is Some(true), it returns Enabled with a saved preference of Some(true). If there is no record, or the saved value is false or empty, it returns Disabled.

Call relations: This is the common translation step for code that reads saved remote-control data. It is called by RemoteControlHandle::resolve_persisted_preference, resolve_unknown_desired_state, and resolve_desired_state_after_account_change when they need to turn database data into the runtime desired state.

Call graph: called by 3 (resolve_persisted_preference, resolve_unknown_desired_state, resolve_desired_state_after_account_change).

async fn resolve_persisted_preference(
        &self,
        app_server_client_name: Option<&str>,
    ) -> io::Result<bool>

Purpose: This figures out, usually during startup or first use, whether remote control should be enabled based on saved data. It is careful not to do that work twice if another task has already resolved the answer.

Data flow: It takes an optional app-server client name, then first checks whether remote control is allowed at all. If it is not allowed, it returns false. It takes the desired-state RPC lock so two requests do not resolve the unknown state at the same time. If the desired state is already known, it returns whether that state is enabled. Otherwise it reads the state database, loads the current remote-control account, normalizes the remote-control URL, builds the persistence key for the client name, fetches the saved enrollment, converts it with desired_state_from_persisted_enrollment, stores that result if the state is still unknown, and returns the final enabled-or-disabled answer.

Call relations: This function sits at the point where runtime state meets saved configuration. It calls load_remote_control_auth to know which account’s enrollment to read, normalize_remote_control_url so the lookup uses the canonical server address, and desired_state_from_persisted_enrollment to interpret the database row. If remote control storage is unavailable, it reports that as an I/O error.

Call graph: calls 3 internal fn (load_remote_control_auth, desired_state_from_persisted_enrollment, normalize_remote_control_url); 1 external calls (matches!).

async fn enable(
        &self,
        app_server_client_name: Option<&str>,
    ) -> io::Result<RemoteControlStatusChangedNotification>

Purpose: This turns remote control on and saves that choice so it survives future runs. It also makes sure there is a valid enrollment with the remote-control server before marking the feature enabled.

Data flow: It receives an optional app-server client name. It first checks permission, then takes a transition lock so another enable-or-disable request cannot race it. It requires a state database, loads the current account, normalizes the remote-control URL, and prepares the persistence key for the client name. It reads current status, locks the current enrollment, and asks the server-enrollment path to reuse or create an enrollment. After enrollment, it reloads auth and refuses to continue if the account changed mid-operation. Then it takes the persistence lock, writes remote_control_enabled = true to the database, creates or updates the persisted enrollment row if needed, publishes the enrollment in memory, updates the desired state to enabled with a saved preference, publishes the environment id to status listeners, and returns the new status notification.

Call relations: This is the durable enable path for RemoteControlHandle. It calls load_remote_control_auth before and after enrollment to avoid saving an enrollment under the wrong account, normalize_remote_control_url for consistent database keys, acquire_persistence_lock before writing saved state, update_persisted_remote_control_enrollment if no existing row was updated, publish_current_enrollment to refresh shared in-memory enrollment data, and RemoteControlStatusPublisher::new to announce the updated environment id.

Call graph: calls 5 internal fn (load_remote_control_auth, acquire_persistence_lock, update_persisted_remote_control_enrollment, normalize_remote_control_url, new); 2 external calls (new, publish_current_enrollment).

async fn start_pairing(
        &self,
        request: StartRemoteControlPairingRequest,
    ) -> io::Result<RemoteControlPairingStartResponse>

Purpose: Starts a new remote-control pairing session for an already enrolled server. It refuses to proceed if the server token is missing or too close to expiry, because pairing must happen with a valid short-lived credential.

Data flow: It takes the current enrollment and a pairing request. It checks whether the token is usable, sends the request as JSON to the backend pairing URL with bearer-token authentication, reads the response, redacts and previews the body for any error messages, verifies that the returned server and environment match this enrollment, parses the expiry time, and returns the pairing code information expected by the app-server protocol.

Call relations: When a caller asks to begin pairing, this method first relies on should_refresh_server_token to decide whether the enrollment is ready. It then uses build_reqwest_client to contact the backend and preview_remote_control_response_body to make failures understandable without leaking secrets. If the token is not usable, it reports the shared pairing_unavailable_error instead of making the backend call.

Call graph: calls 3 internal fn (should_refresh_server_token, preview_remote_control_response_body, build_reqwest_client); 5 external calls (parse, new, other, format!, pairing_unavailable_error).

async fn pairing_status(
        &self,
        request: RemoteControlPairingStatusRequest,
    ) -> io::Result<RemoteControlPairingStatusResponse>

Purpose: Checks whether a pairing request has been claimed by a remote client. It is used after pairing has started, so the local app can poll for progress.

Data flow: It receives the enrollment and a status request. It confirms the server token is present and fresh enough, posts the request to the backend status URL with bearer-token authentication, reads and previews the response body for diagnostics, converts backend error codes into local error kinds, parses the backend response, and returns only the public claimed status.

Call relations: This method follows the same readiness gate as start_pairing by calling should_refresh_server_token. It uses build_reqwest_client for the HTTP request and preview_remote_control_response_body for safe error text. If the enrollment needs a token refresh, it stops early with pairing_unavailable_error.

Call graph: calls 3 internal fn (should_refresh_server_token, preview_remote_control_response_body, build_reqwest_client); 3 external calls (new, format!, pairing_unavailable_error).

fn should_refresh_server_token(&self) -> bool

Purpose: Decides whether the temporary remote-control server token should be refreshed before use. It treats a missing token or a token expiring within the safety window as unusable.

Data flow: It reads the enrollment’s optional token and optional expiry time. If either is absent, or if the expiry time is at or before the current time plus a 30-second buffer, it returns true; otherwise it returns false.

Call relations: start_pairing and pairing_status call this before making backend pairing requests. That keeps those flows from using stale credentials and pushes the caller toward the refresh path first.

Call graph: called by 2 (pairing_status, start_pairing).

fn clear_server_token(&mut self)

Purpose: Removes the short-lived server token from an enrollment. This is useful when another part of the system knows the token should no longer be trusted.

Data flow: It takes a mutable enrollment. It changes remote_control_token and expires_at from whatever they were to None, leaving the stable enrollment IDs and server name untouched.

Call relations: The wider remote-control flow calls this through clear_pairing_server_token when it needs to forget the temporary credential while keeping the enrollment identity.

Call graph: called by 1 (clear_pairing_server_token).

async fn load_persisted_remote_control_enrollment(
    state_db: Option<&StateRuntime>,
    remote_control_target: &RemoteControlTarget,
    account_id: &str,
    app_server_client_name: Option<&str>,

Purpose: Loads a previously saved remote-control enrollment from the local state database. This lets the app reuse the same server identity after restart instead of enrolling as a new server every time.

Data flow: It receives an optional state database, the remote-control target, the account ID, and an optional client name. If the database is unavailable, it returns a not-found style error. Otherwise it looks up a matching saved enrollment by backend URL, account, and client name. If found, it builds a RemoteControlEnrollment with the saved stable IDs but no temporary token; if not found, it returns None.

Call relations: load_or_enroll_server and prepare_remote_control_enrollment call this early in the remote-control setup path. It logs whether it reused an enrollment or found none, and it warns if the state database lookup itself fails.

Call graph: called by 2 (load_or_enroll_server, prepare_remote_control_enrollment); 6 external calls (clone, new, other, format!, info!, warn!).

async fn update_persisted_remote_control_enrollment(
    state_db: Option<&StateRuntime>,
    remote_control_target: &RemoteControlTarget,
    account_id: &str,
    app_server_client_name: Option<&str

Purpose: Saves or clears the stable enrollment record in local state. It is how the app remembers which server ID belongs to a target backend and account.

Data flow: It receives the optional state database, target, account, optional client name, optional enrollment, and optional enabled flag. If an enrollment is provided, it verifies the account matches, writes or updates the record, and logs the saved server and environment IDs. If no enrollment is provided, it deletes the matching record and logs how many rows were removed.

Call relations: Enrollment and settings flows call this after creating, reusing, enabling, or clearing remote control. Tests also call it to prove records round-trip correctly and that deletion only removes the matching target/account entry.

Call graph: called by 12 (load_or_enroll_pairing_server, enable, clearing_persisted_remote_control_enrollment_removes_only_matching_entry, persisted_remote_control_enrollment_round_trips_by_target_and_account, persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_preserves_stale_enrollment_when_reenrollment_fails, remote_control_http_mode_reenrolls_after_explicit_missing_server_404, remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment, remote_control_http_mode_refreshes_persisted_enrollment_before_connecting (+2 more)); 4 external calls (new, other, format!, info!).

fn preview_remote_control_response_body(body: &[u8]) -> String

Purpose: Creates a safe, short preview of a backend response body for error messages. It helps developers diagnose backend problems without dumping huge responses or exposing secrets.

Data flow: It receives raw response bytes. It converts them to text, trims whitespace, returns <empty> if nothing remains, redacts sensitive JSON fields when possible, and truncates the result to a fixed maximum length without cutting through the middle of a character.

Call relations: HTTP-facing flows such as pairing, enrollment, client listing, client revocation, and websocket connection error formatting use this whenever they need to include a backend response body in an error. It delegates the secret-hiding step to redact_remote_control_response_body.

Call graph: calls 1 internal fn (redact_remote_control_response_body); called by 6 (list_remote_control_clients, revoke_remote_control_client, pairing_status, start_pairing, send_remote_control_server_request, format_remote_control_websocket_connect_error); 1 external calls (from_utf8_lossy).

fn redact_remote_control_response_body(body: &str) -> String

Purpose: Hides secrets from a response body that looks like a JSON object. It protects fields such as server tokens and pairing codes before text is logged or returned in an error.

Data flow: It receives response text. If the text is valid JSON and the top-level value is an object, it replaces remote_control_token, pairing_code, and manual_pairing_code values with <redacted> and returns the JSON text. If the body is not such a JSON object, it returns the original text unchanged.

Call relations: preview_remote_control_response_body calls this as its redaction step. That keeps the sensitive-field knowledge in one small helper while the preview function focuses on trimming and length limits.

Call graph: called by 1 (preview_remote_control_response_body); 1 external calls (String).

fn format_headers(headers: &HeaderMap) -> String

Purpose: Extracts a small set of useful tracing headers from an HTTP response. These IDs help connect a local error to backend logs or Cloudflare request routing information.

Data flow: It receives an HTTP header map. It looks for a request ID header, falling back from x-request-id to x-oai-request-id, and also looks for cf-ray. Missing values become <none> and invalid text becomes <invalid utf-8>. It returns one compact string containing both values.

Call relations: send_remote_control_server_request uses this when building backend error messages, so a failed enrollment or refresh can be matched to server-side diagnostics.

Call graph: called by 1 (send_remote_control_server_request); 2 external calls (get, format!).

async fn enroll_remote_control_server(
    remote_control_target: &RemoteControlTarget,
    auth: &RemoteControlConnectionAuth,
    installation_id: &str,
    server_name: &str,
) -> io::Result<Remote

Purpose: Registers this app server with the remote-control backend for the first time. It creates the server identity that later pairing and websocket flows rely on.

Data flow: It receives the target backend, connection authentication, installation ID, and desired server name. It builds an enrollment request containing the server name, operating system, CPU architecture, app-server version, and installation ID. It sends that request to the backend, receives server and environment IDs plus a temporary token, builds a RemoteControlEnrollment, stores the token and expiry on it, and returns the completed enrollment.

Call relations: Higher-level flows such as enroll_pairing_server and enroll_and_persist_remote_control_server call this when no reusable enrollment exists or a new enrollment is needed. It relies on send_remote_control_server_request for the HTTP exchange and update_remote_control_server_token to attach the returned temporary credential.

Call graph: calls 1 internal fn (update_remote_control_server_token); called by 3 (enroll_remote_control_server_parse_failure_includes_response_body, enroll_pairing_server, enroll_and_persist_remote_control_server); 2 external calls (clone, env!).

async fn refresh_remote_control_server(
    auth: &RemoteControlConnectionAuth,
    installation_id: &str,
    enrollment: &mut RemoteControlEnrollment,
) -> io::Result<()>

Purpose: Refreshes the temporary token for an existing remote-control enrollment. This lets the app keep using the same server identity without re-enrolling.

Data flow: It receives authentication, installation ID, and a mutable enrollment. It sends the current server ID and installation ID to the refresh URL, receives a fresh token and expiry, checks that the backend returned the same server and environment IDs, then updates the enrollment’s token fields. If the IDs do not match, it returns an error instead of silently changing identity.

Call relations: refresh_pairing_enrollment and prepare_remote_control_enrollment call this when the current token is missing or nearing expiry. It uses the shared server-request sender and then hands token parsing and storage to update_remote_control_server_token.

Call graph: calls 1 internal fn (update_remote_control_server_token); called by 2 (refresh_pairing_enrollment, prepare_remote_control_enrollment); 2 external calls (other, format!).

async fn send_remote_control_server_request(
    url: &str,
    auth: &RemoteControlConnectionAuth,
    installation_id: &str,
    request: &Request,
    action: &str,
    response_kind: &str,
) -> io

Purpose: Sends a JSON request to the remote-control backend for server enrollment-style operations and parses the JSON response. It centralizes the repeated HTTP behavior for enrolling and refreshing.

Data flow: It receives a URL, authentication, installation ID, request body, action name, and response label. It builds a client, adds authentication headers plus account and installation headers, posts the JSON request with a timeout, reads the response body, creates a safe body preview, turns non-success HTTP statuses into local errors, and parses a successful JSON body into the requested response type.

Call relations: Enrollment and refresh flows use this helper so they share the same timeout, headers, response parsing, and error format. It calls format_headers to include request tracing IDs and preview_remote_control_response_body so response snippets are safe to show.

Call graph: calls 3 internal fn (format_headers, preview_remote_control_response_body, build_reqwest_client); 3 external calls (new, new, format!).

fn update_remote_control_server_token(
    enrollment: &mut RemoteControlEnrollment,
    url: &str,
    token: String,
    expires_at: String,
) -> io::Result<()>

Purpose: Stores a newly received temporary server token and its expiry time on an enrollment. It keeps token parsing in one place.

Data flow: It receives a mutable enrollment, the URL used for the backend call, a token string, and an expiry timestamp string. It parses the expiry as RFC 3339 date-time text, then writes the token and parsed expiry into the enrollment. If parsing fails, it returns an error that names the backend URL.

Call relations: enroll_remote_control_server calls this after first enrollment, and refresh_remote_control_server calls it after token refresh. Both flows depend on it to turn backend text into a usable expiry time.

Call graph: called by 2 (enroll_remote_control_server, refresh_remote_control_server); 1 external calls (parse).

async fn remote_control_state_runtime(codex_home: &TempDir) -> Arc<StateRuntime>

Purpose: Creates a temporary state database runtime for tests. It gives persistence tests a real local database without touching a user’s actual data.

Data flow: It receives a temporary directory. It initializes StateRuntime rooted at that directory with a test provider name and returns it wrapped for shared use by async test code.

Call relations: The persistence tests call this before saving or loading enrollments. It keeps their setup short and consistent.

Call graph: calls 1 internal fn (init); 1 external calls (path).

fn remote_control_enrollment_refreshes_server_token_before_expiry()

Purpose: Verifies the 30-second token refresh safety window. The test proves that a token expiring soon is considered stale while one expiring just later is still usable.

Data flow: It builds two nearly identical enrollments: one with a token expiring in 29 seconds and one expiring in 31 seconds. It calls should_refresh_server_token on both and checks that only the first asks for refresh.

Call relations: This test directly protects the behavior used by start_pairing and pairing_status, where using a token too close to expiry could make pairing unreliable.

Call graph: calls 1 internal fn (normalize_remote_control_url); 3 external calls (now_utc, assert!, seconds).

fn preview_remote_control_response_body_redacts_server_token()

Purpose: Checks that response previews hide sensitive remote-control fields. It makes sure error messages do not reveal tokens or pairing codes.

Data flow: It feeds a JSON response containing a server ID, token, pairing code, and manual pairing code into preview_remote_control_response_body. It parses the preview back as JSON and asserts that the sensitive fields were replaced with <redacted> while the server ID remained visible.

Call relations: This test protects the redaction path used by HTTP error reporting throughout this file and related remote-control client flows.

Call graph: 1 external calls (assert_eq!).

async fn persisted_remote_control_enrollment_round_trips_by_target_and_account()

Purpose: Proves that saved enrollments can be loaded again and are separated by backend target and account. This prevents one account or remote-control environment from accidentally reusing another’s server identity.

Data flow: It creates a temporary state database, two different remote-control targets, and two enrollment records for the same account. It saves both records, then loads by different target/account combinations and checks that the matching entries come back and a missing account returns None.

Call relations: The test uses update_persisted_remote_control_enrollment to write records and load_persisted_remote_control_enrollment to read them back. It supports the startup paths that reuse enrollment records.

Call graph: calls 2 internal fn (update_persisted_remote_control_enrollment, normalize_remote_control_url); 3 external calls (new, remote_control_state_runtime, assert_eq!).

async fn clearing_persisted_remote_control_enrollment_removes_only_matching_entry()

Purpose: Verifies that clearing one persisted enrollment does not delete unrelated enrollments. This matters when the same machine may know about more than one remote-control backend target.

Data flow: It creates a temporary state database, saves two enrollments for different targets, then clears only the first target’s record. It loads both afterward and checks that the first is gone while the second is still present.

Call relations: The test exercises the delete branch of update_persisted_remote_control_enrollment and confirms that load_persisted_remote_control_enrollment still finds the untouched record.

Call graph: calls 2 internal fn (update_persisted_remote_control_enrollment, normalize_remote_control_url); 3 external calls (new, remote_control_state_runtime, assert_eq!).

async fn enroll_remote_control_server_parse_failure_includes_response_body()

Purpose: Checks that a malformed enrollment response produces an error containing the response body. This makes backend integration failures much easier to diagnose.

Data flow: It starts a tiny local TCP server, points a normalized remote-control target at it, and has the server return JSON that is missing required enrollment fields. It calls enroll_remote_control_server, expects parsing to fail, and compares the full error text to the expected message including the safe response body preview.

Call relations: This test drives the real enrollment path through enroll_remote_control_server. Its local server helpers, accept_http_request and respond_with_json, provide a controlled backend response.

Call graph: calls 2 internal fn (enroll_remote_control_server, normalize_remote_control_url); 8 external calls (bind, accept_http_request, respond_with_json, assert_eq!, unauthenticated_auth_provider, format!, json!, spawn).

async fn accept_http_request(listener: &TcpListener) -> TcpStream

Purpose: Accepts one simple HTTP request in a test and returns the underlying socket so the test can write a response. It is a small stand-in for a backend server.

Data flow: It receives a TCP listener, waits up to five seconds for a connection, reads the request line and headers until the blank line that ends HTTP headers, and returns the stream positioned for writing a response.

Call relations: The parse-failure enrollment test uses this helper inside a spawned task before calling respond_with_json. It keeps the fake server just detailed enough for the HTTP client to talk to it.

Call graph: 5 external calls (new, from_secs, new, accept, timeout).

async fn respond_with_json(mut stream: TcpStream, body: serde_json::Value)

Purpose: Writes a minimal HTTP JSON response to a test TCP stream. It lets tests control exactly what body the enrollment code receives.

Data flow: It receives a TCP stream and a JSON value. It converts the JSON to text, builds an HTTP 200 response with content type, content length, and connection-close headers, writes it to the stream, and flushes the bytes.

Call relations: The parse-failure enrollment test calls this after accept_http_request has captured the client connection. Together they simulate a backend response without running a full web server.

Call graph: 4 external calls (flush, write_all, to_string, format!).

fn new(
        server_event_tx: mpsc::Sender<QueuedServerEnvelope>,
        transport_event_tx: mpsc::Sender<TransportEvent>,
        shutdown_token: &CancellationToken,
    ) -> Self

Purpose: Creates an empty tracker ready to remember remote clients and forward their events. It also creates a child cancellation token, which is like giving the tracker its own off-switch connected to the larger server shutdown switch.

Data flow: It receives a sender for server-bound remote-control events, a sender for transport-layer events, and a shutdown token. It builds empty maps for clients and legacy stream ids, creates an empty task set for outbound forwarding tasks, and returns a new ClientTracker holding all of that.

Call relations: Tests call this to set up a tracker before simulating client messages. After construction, other methods such as handle_message, close_client, and shutdown use the stored senders and cancellation token to drive the client lifecycle.

Call graph: called by 11 (cancelled_outbound_task_emits_connection_closed, close_client_keeps_forwarding_after_caller_is_aborted, close_client_waits_for_transport_event_queue_capacity, incoming_message_timeout_does_not_advance_seq_id, initialize_timeout_closes_open_connection, initialize_with_new_stream_id_opens_new_connection_for_same_client, legacy_initialize_without_stream_id_resets_inbound_seq_id, non_close_transport_event_send_times_out_when_queue_stays_full, shutdown_cancels_blocked_outbound_forwarding, new (+1 more)); 3 external calls (child_token, new, new).

async fn bookkeep_join_set(&mut self) -> Option<(ClientId, StreamId)>

Purpose: Waits for one outbound client task to finish and reports which client stream ended. This lets the owner of the tracker notice when a background sender has stopped and then close the matching connection cleanly.

Data flow: It waits on the tracker’s JoinSet, which is a collection of background tasks. If a task finishes normally, it returns that task’s client id and stream id. If tasks fail internally, it skips them and keeps waiting; if there is nothing left, it waits forever rather than returning a misleading result.

Call relations: The outbound tasks are created by handle_message through run_client_outbound. A caller can use bookkeep_join_set after one of those tasks exits, then call close_client to send the final connection-closed event.

Call graph: 2 external calls (join_next, pending).

async fn shutdown(&mut self)

Purpose: Stops the tracker and all clients it knows about. This is the orderly shutdown path for remote-control connections.

Data flow: It first cancels the tracker’s shutdown token, which tells child tasks to stop. Then it repeatedly picks remaining clients and closes them. Finally, it drains the task set so background outbound tasks have finished before shutdown completes.

Call relations: This method calls close_client for each known client and then drain_join_set. Tests use it to prove shutdown does not hang even when outbound forwarding is blocked.

Call graph: calls 2 internal fn (close_client, drain_join_set); 1 external calls (cancel).

async fn drain_join_set(&mut self)

Purpose: Waits until all background outbound tasks have finished. It is a cleanup helper used during shutdown.

Data flow: It repeatedly waits for the next completed task in the JoinSet and discards the result. When no more tasks remain, it returns.

Call relations: shutdown calls this after cancelling and closing clients. It does not create or close clients itself; it only makes sure the spawned forwarding work has stopped.

Call graph: called by 1 (shutdown); 1 external calls (join_next).

async fn handle_message(
        &mut self,
        client_envelope: ClientEnvelope,
    ) -> Result<(), Stopped>

Purpose: Processes one message envelope from a remote-control client. It decides whether to open a new connection, forward a client message, answer a ping, ignore a duplicate, or close a connection.

Data flow: It receives a ClientEnvelope containing the client id, optional stream id, optional sequence number, and event. It works out the effective stream id, including fallback behavior for older clients. For initialize messages, it may open a new connection, create a reply channel, spawn an outbound forwarding task, and forward the initialize JSON-RPC message inward. For later messages, it updates activity time and forwards them if they are new. For pings, it updates status or sends an unknown pong. For client-closed events, it closes the matching client.

Call relations: This is the main entry point used when remote-control input arrives. It calls close_client when a stream must be replaced or closed, send_transport_event when the app-server transport layer must be told something, record_inbound_message_delivery after successful delivery, remove_client for rollback after failed initialization, and spawn_connection_closed when cleanup must continue without blocking reconnects.

Call graph: calls 5 internal fn (close_client, record_inbound_message_delivery, remove_client, send_transport_event, spawn_connection_closed); 9 external calls (child_token, now, spawn, run_client_outbound, clone, matches!, next_connection_id, spawn, channel).

async fn run_client_outbound(
        client_id: ClientId,
        stream_id: StreamId,
        server_event_tx: mpsc::Sender<QueuedServerEnvelope>,
        mut writer_rx: mpsc::Receiver<QueuedOutgoin

Purpose: Runs the background loop that sends server replies and pong-status updates back to one remote-control client stream. It is the return lane for messages after a client connection has been opened.

Data flow: It receives a client id, stream id, a sender for queued server envelopes, a receiver for outgoing app-server messages, a receiver watching pong status, and a cancellation token. It waits for one of three things: cancellation, a server message to forward, or a pong status change. It wraps each outbound item in a server envelope with the right client and stream ids, sends it, and exits if cancellation or channel closure happens. When it exits, it returns the client id and stream id.

Call relations: handle_message spawns this when an initialize message opens a connection. bookkeep_join_set later observes its returned client key so the tracker owner can clean up the connection.

Call graph: 1 external calls (select!).

async fn close_expired_clients(
        &mut self,
    ) -> Result<Vec<(ClientId, StreamId)>, Stopped>

Purpose: Finds clients that have been quiet for too long and closes them. This prevents abandoned remote-control sessions from staying open forever.

Data flow: It reads the current time, checks every stored client’s last activity time, collects the client-stream keys that are older than the idle timeout, and closes each one. It returns the list of client streams it closed, or an error if sending a close event fails.

Call relations: An idle-sweep loop elsewhere can call this periodically. It relies on remote_control_client_is_alive to decide who is still active and calls close_client to do the actual shutdown work.

Call graph: calls 1 internal fn (close_client); 1 external calls (now).

async fn close_client(
        &mut self,
        client_key: &(ClientId, StreamId),
    ) -> Result<(), Stopped>

Purpose: Closes one tracked client stream if it exists. It removes the client from the tracker, tells its outbound task to stop, and notifies the transport layer that the connection is closed.

Data flow: It receives a client id and stream id pair. If no such client is stored, it returns successfully without changing anything. If found, it removes the client state, cancels that client’s disconnect token, and sends a ConnectionClosed transport event for the stored connection id.

Call relations: handle_message calls this for explicit client closes or reconnects on the same stream. close_expired_clients calls it for idle clients, and shutdown calls it for every remaining client.

Call graph: calls 2 internal fn (remove_client, send_transport_event); called by 3 (close_expired_clients, handle_message, shutdown).

fn remove_client(&mut self, client_key: &(ClientId, StreamId)) -> Option<ClientState>

Purpose: Deletes a client stream from the tracker’s internal records. It also cleans up the legacy stream-id shortcut if that shortcut pointed to the removed stream.

Data flow: It receives a client id and stream id pair. It removes the matching ClientState from the clients map. If the legacy-stream map for that client points to the same stream, it removes that legacy entry too. It returns the removed state, or nothing if the client was not known.

Call relations: close_client uses this as the first step of normal closure. handle_message also uses it during initialization rollback if a newly opened connection cannot receive its first message.

Call graph: called by 2 (close_client, handle_message).

async fn send_transport_event(&self, event: TransportEvent) -> Result<(), Stopped>

Purpose: Sends an event to the app-server transport layer, with safeguards so a stuck receiver does not block most remote-control work forever. Connection-closed events get special treatment because cleanup must be reliable.

Data flow: It receives a TransportEvent. If it is ConnectionClosed, it hands it to send_connection_closed. For other events, it names the event for logging, tries to send it through the transport-event channel, and waits only up to a fixed timeout. It returns success if the event is accepted, or Stopped if the receiver is gone or the timeout expires.

Call relations: handle_message uses this when opening connections and forwarding inbound client messages. close_client uses it when reporting closure. It calls transport_event_name for clearer warning logs and send_connection_closed for close events.

Call graph: calls 2 internal fn (send_connection_closed, transport_event_name); called by 2 (close_client, handle_message); 3 external calls (send, timeout, warn!).

fn record_inbound_message_delivery(
        &mut self,
        client_key: &(ClientId, StreamId),
        seq_id: Option<u64>,
    )

Purpose: Remembers the latest inbound sequence number only after the message has actually reached the app-server transport layer. This avoids treating a failed delivery as if it had succeeded.

Data flow: It receives a client stream key and an optional sequence number. If a sequence number is present and the client is still tracked, it stores that number as the latest delivered inbound message for that client.

Call relations: handle_message calls this after send_transport_event succeeds for a client message. Later calls to handle_message use the stored number to ignore duplicate retries.

Call graph: called by 1 (handle_message).

async fn send_connection_closed(&self, connection_id: ConnectionId) -> Result<(), Stopped>

Purpose: Forwards a connection-closed event in a way that survives caller cancellation. Closing is cleanup, so the code tries harder to deliver it than ordinary messages.

Data flow: It receives a connection id, starts a separate task to send the close event, and waits for that task’s result. If the spawned task succeeds, it returns that result. If the task itself fails, it logs a warning and reports Stopped.

Call relations: send_transport_event calls this whenever the event is ConnectionClosed. This method delegates the actual sending to spawn_connection_closed.

Call graph: calls 1 internal fn (spawn_connection_closed); called by 1 (send_transport_event); 1 external calls (warn!).

fn spawn_connection_closed(
        &self,
        connection_id: ConnectionId,
    ) -> JoinHandle<Result<(), Stopped>>

Purpose: Starts a detached task that sends a ConnectionClosed event to the transport layer. This lets close delivery continue even if the original caller is aborted.

Data flow: It receives a connection id, clones the transport-event sender, logs what it is doing, and spawns an async task. That task sends the ConnectionClosed event and returns success or Stopped if the receiver has disappeared.

Call relations: send_connection_closed uses this for normal close-event delivery. handle_message also uses it during initialization rollback, where the first message could not be forwarded and the code must close the just-opened connection without blocking a reconnect.

Call graph: called by 2 (handle_message, send_connection_closed); 3 external calls (clone, info!, spawn).

fn transport_event_name(event: &TransportEvent) -> &'static str

Purpose: Turns a transport event into a short text label for logs. This makes warnings easier to read without printing the whole event.

Data flow: It receives a reference to a TransportEvent and matches its variant. It returns one of the fixed strings: connection_opened, connection_closed, or incoming_message.

Call relations: send_transport_event calls this before attempting a timed send, so timeout and receiver-dropped warnings can say which kind of event failed.

Call graph: called by 1 (send_transport_event).

fn remote_control_message_starts_connection(message: &JSONRPCMessage) -> bool

Purpose: Checks whether a JSON-RPC message is the initialize request that begins a remote-control connection. The tracker uses this as the doorway for creating new connections.

Data flow: It receives a JSON-RPC message. It returns true only when the message is a request whose method name is exactly initialize; all notifications, responses, and other request methods return false.

Call relations: handle_message uses this decision to tell a first connection-opening message apart from ordinary later messages.

Call graph: 1 external calls (matches!).

fn remote_control_client_is_alive(client: &ClientState, now: Instant) -> bool

Purpose: Decides whether a client has been active recently enough to keep. It is the small rule behind idle-client cleanup.

Data flow: It receives a client state and the current time. It compares now with the client’s last activity time and returns true if the gap is less than the remote-control idle timeout.

Call relations: close_expired_clients uses this helper while scanning the clients map, then closes any client for which this returns false.

Call graph: 1 external calls (duration_since).

fn initialize_envelope(client_id: &str) -> ClientEnvelope

Purpose: Builds a test client envelope containing an initialize request without a stream id. It represents the older client behavior that the tracker still supports.

Data flow: It receives a client id string and passes it to initialize_envelope_with_stream_id with no stream id. The result is a ready-to-send ClientEnvelope for tests.

Call relations: Several tests use this helper when they want to exercise the legacy stream-id path instead of the newer explicit stream-id path.

Call graph: 1 external calls (initialize_envelope_with_stream_id).

fn initialize_envelope_with_stream_id(
        client_id: &str,
        stream_id: Option<&str>,
    ) -> ClientEnvelope

Purpose: Builds a test client envelope containing an initialize request, optionally with a stream id. This gives tests a consistent way to open simulated remote-control connections.

Data flow: It receives a client id string and an optional stream id string. It creates a JSON-RPC initialize request with sample client information, wraps it as a ClientMessage event, adds the ids and sequence number, and returns the ClientEnvelope.

Call relations: The test cases call this before passing the envelope to ClientTracker::handle_message. It is the shared setup for both modern stream-id tests and legacy fallback tests.

Call graph: 4 external calls (Request, Integer, new, json!).

fn initialized_notification() -> JSONRPCMessage

Purpose: Creates a simple JSON-RPC initialized notification for tests. This is used as a normal follow-up message after initialization.

Data flow: It takes no input. It returns a JSON-RPC notification whose method is initialized and whose parameters are absent.

Call relations: Tests use this helper when they need a harmless inbound message to fill queues, retry delivery, or check sequence-number behavior.

Call graph: 1 external calls (Notification).

async fn cancelled_outbound_task_emits_connection_closed()

Purpose: Verifies that when an outbound client task is cancelled, the tracker can notice it and emit a connection-closed event. This protects cleanup for externally cancelled client streams.

Data flow: The test creates channels and a tracker, sends an initialize envelope, reads the connection-opened and incoming-message events, cancels the disconnect token, waits for bookkeep_join_set to report the ended client, calls close_client, and checks that the matching connection-closed event appears.

Call relations: It exercises ClientTracker::new, handle_message, bookkeep_join_set, and close_client together. It proves the background outbound task’s returned client key is enough to drive final closure.

Call graph: calls 1 internal fn (new); 7 external calls (new, from_secs, initialize_envelope, assert_eq!, channel, panic!, timeout).

async fn shutdown_cancels_blocked_outbound_forwarding()

Purpose: Verifies shutdown does not hang when an outbound server-event queue is already full. This matters because shutdown must be able to stop even under backpressure, meaning when a queue cannot accept more messages.

Data flow: The test fills a small server-event queue, opens a client, sends an outgoing message through the writer, and then calls shutdown with a timeout. The expected result is that shutdown completes instead of waiting forever for queue space.

Call relations: It uses ClientTracker::new, handle_message, the outbound task started by handle_message, and ClientTracker::shutdown. The test confirms shutdown cancellation reaches run_client_outbound.

Call graph: calls 2 internal fn (new, new); 10 external calls (new, from_secs, ConfigWarning, AppServerNotification, initialize_envelope, new, new, channel, panic!, timeout).

async fn non_close_transport_event_send_times_out_when_queue_stays_full()

Purpose: Checks that ordinary transport events fail with a timeout when the transport-event queue remains full. This prevents remote-control message handling from freezing indefinitely.

Data flow: The test creates a transport-event channel with capacity one, fills it, then asks the tracker to send an IncomingMessage event. Because nothing drains the queue, the send times out and the test expects an error.

Call relations: It uses ClientTracker::new and send_transport_event directly. It focuses on the timeout path for non-close events.

Call graph: calls 1 internal fn (new); 5 external calls (new, initialized_notification, assert!, channel, next_connection_id).