Shutdown, cleanup, and teardown

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

Purpose: Starts and drives the updater loop. On Unix, it waits for shutdown signals, delays the first update, runs update checks forever, and exits cleanly when asked to terminate. On non-Unix systems, it reports that this updater style is unsupported.

Data flow: It begins with no caller-provided input, then creates a listener for the operating system terminate signal and reads the identity of the currently running updater executable. It waits for the initial delay unless a shutdown arrives first. After that, it repeatedly asks update_once to perform a single update pass, waits for the regular update interval, and returns success when the loop is told to stop. On unsupported platforms, it immediately returns an error.

Call relations: This is called by run_pid_update_loop when the daemon wants to start the pid-managed updater. It calls current_updater_identity once at startup, uses sleep_or_terminate between work cycles, and calls update_once for each actual update attempt. It also installs the terminate signal listener so the rest of the loop can stop promptly.

Call graph: calls 3 internal fn (current_updater_identity, sleep_or_terminate, update_once); called by 1 (run_pid_update_loop); 3 external calls (terminate, bail!, signal).

async fn sleep_or_terminate(duration: Duration, terminate: &mut Signal) -> bool

Purpose: Waits for either a timer to finish or a shutdown request to arrive. It lets the updater pause without becoming deaf to termination.

Data flow: It receives a duration and a mutable terminate-signal listener. It waits on both at the same time: the timer and the next terminate signal. It returns false if the timer completed normally, or true if a terminate signal arrived first.

Call relations: run uses this during the initial delay and between hourly update passes. update_once uses it when the daemon is busy and the updater needs to retry soon. It is the small helper that keeps long waits responsive to shutdown.

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

async fn update_once(
    running_updater_identity: &ExecutableIdentity,
    terminate: &mut Signal,
) -> Result<UpdateLoopControl>

Purpose: Performs one full update attempt: install the latest standalone Codex, inspect the managed binary, choose the right restart behavior, and try to restart the daemon if appropriate.

Data flow: It receives the identity of the updater executable that was running when the loop started, plus the terminate-signal listener. First it runs install_latest_standalone. Then it reads daemon settings from the environment, resolves the path to the managed Codex binary, and computes that binary’s identity. It compares the two identities to choose restart and updater-refresh modes. It then tries to restart the daemon if it is running. If the daemon is busy, it waits briefly and retries unless a terminate signal arrives. It returns Continue when the update pass is complete, or Stop when shutdown should end the whole loop.

Call relations: run calls this once per update cycle. Inside the cycle it hands off installation to install_latest_standalone, identity checking to executable_identity and resolved_managed_codex_bin, policy selection to update_modes_for_identities, and restart work to the daemon’s try_restart_if_running. Its retry path uses sleep_or_terminate so shutdown still wins over retrying.

Call graph: calls 6 internal fn (from_environment, executable_identity, resolved_managed_codex_bin, install_latest_standalone, sleep_or_terminate, update_modes_for_identities); called by 1 (run); 1 external calls (recv).

async fn current_updater_identity() -> Result<ExecutableIdentity>

Purpose: Figures out exactly which updater executable is currently running. This matters because the loop later compares it with the managed Codex binary to decide whether the updater itself should be refreshed.

Data flow: It reads the current process’s executable path from the operating system. It then passes that path to executable_identity, which produces an identity value for the file. The result is returned to the caller, or an error is returned if the path or identity cannot be read.

Call relations: run calls this once before the first update delay. The identity it returns is carried into every update_once call, where it is compared with the managed binary’s identity.

Call graph: calls 1 internal fn (executable_identity); called by 1 (run); 1 external calls (current_exe).

fn update_modes_for_identities(
    running_updater_identity: &ExecutableIdentity,
    managed_identity: &ExecutableIdentity,
) -> (RestartMode, UpdaterRefreshMode)

Purpose: Chooses the restart policy by comparing the updater that is currently running with the managed Codex binary. In plain terms, it answers: are we already running the managed version, or should we switch to it?

Data flow: It receives two executable identities: one for the running updater and one for the managed Codex binary. If they match, it returns a conservative mode: restart only if the version changed, and do not refresh the updater process. If they differ, it returns a stronger mode: always restart and re-execute the updater if the managed binary changed.

Call relations: update_once calls this after it has identified both executables. The returned modes are passed into the daemon restart attempt, which uses them to decide whether to restart the service and whether to replace the updater process.

Call graph: called by 1 (update_once).

fn reexec_managed_updater(managed_codex_bin: &std::path::Path) -> Result<()>

Purpose: Replaces the currently running updater process with the managed Codex binary. This is how the updater stops running from an old or standalone executable and continues from the installed managed one.

Data flow: It receives the path to the managed Codex binary. It starts an operating-system exec, which means the current process is replaced in place rather than launching a separate child process. The new process is invoked with arguments that tell it to run the app-server daemon pid update loop. If replacement fails, the function returns an error explaining which binary could not be used.

Call relations: This is called by try_restart_if_running when the restart logic decides the updater should refresh itself. Unlike ordinary helper calls, a successful exec does not return to the old code at all; the process has become the managed updater.

Call graph: called by 1 (try_restart_if_running); 1 external calls (new).

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

Purpose: Downloads and runs the standalone Codex installer script. This is the step that actually brings the local Codex installation up to date before the daemon restart decision is made.

Data flow: It fetches https://chatgpt.com/codex/install.sh, checks that the web request succeeded, and reads the script bytes. It then starts /bin/sh -s with standard input connected, sends the downloaded script into that shell, hides the script’s output by sending stdout and stderr to null, and waits for the shell to finish. It returns success if the installer exits successfully, or an error if fetching, starting, writing, waiting, or the installer itself fails.

Call relations: update_once calls this at the start of every update pass. Once this installer has run, update_once can inspect the managed Codex binary and decide whether the daemon and updater need to restart.

Call graph: called by 1 (update_once); 5 external calls (null, piped, bail!, new, get).

fn new() -> Self

Purpose: Creates a fresh gate that is open and ready to let RPC handler work start. It also creates an empty tracker so active work can be counted from the beginning.

Data flow: Nothing is passed in. The function sets the internal accepting flag to true and creates a new task tracker with no active tokens. It returns a ConnectionRpcGate ready for use on a connection.

Call relations: This is the starting point for the gate. Tests create gates with it before checking open, closed, and shutdown behavior, and the Default implementation also uses it so callers can create the same open gate through Rust’s standard default pattern.

Call graph: called by 8 (close_returns_while_started_run_remains_active, run_drops_future_without_polling_after_close, run_executes_while_open, run_is_counted_before_handler_body_continues, shutdown_drops_late_runs_while_waiting_for_inflight_work, shutdown_waits_for_started_run_to_finish, new, gate); 2 external calls (new, new).

async fn run(&self, future: F)

Purpose: Runs one RPC handler only if the connection is still accepting work. If the gate has already been closed, it returns without starting the handler at all.

Data flow: It receives a future, which is async work that has not necessarily run yet. It first locks the accepting flag. If the flag is false, it drops the future untouched and returns. If the flag is true, it takes a tracker token, releases the lock, awaits the future until it finishes, and then drops the token so the active-work count goes down.

Call relations: This is the gate’s main doorway for handler execution. Connection code would wrap each initialized RPC handler in this method. It asks the task tracker for a token before letting the handler body continue, so shutdown later has something reliable to wait on.

Call graph: 1 external calls (token).

async fn close(&self)

Purpose: Closes the gate so no later RPC handlers can start. It does not wait for already-started handlers to finish.

Data flow: It reads and changes the internal accepting flag under the mutex. The flag changes from true, or remains false if already closed, to false. It also closes the task tracker so no new tracked work should be accepted. It returns once the gate is closed, even if some work is still active.

Call relations: shutdown calls this as its first step. Tests also call it directly to prove that closing blocks later run calls while leaving already-started work alone.

Call graph: called by 1 (shutdown); 1 external calls (close).

async fn shutdown(&self)

Purpose: Performs a graceful shutdown of the gate. It stops new RPC handlers from starting, then waits until all handlers that already started have finished.

Data flow: It takes the existing gate state. First it calls close, which turns off new entries. Then it waits on the task tracker until every active token has been dropped. It returns only after there is no tracked in-flight work left.

Call relations: This is the full shutdown path for connection cleanup. It builds directly on close, then hands off to the tracker’s waiting mechanism so callers can safely know that handler work has drained.

Call graph: calls 1 internal fn (close); 1 external calls (wait).

async fn is_accepting(&self) -> bool

Purpose: Reports whether the gate is currently open to new work. This helper exists only for tests.

Data flow: It locks the accepting flag, copies out the boolean value, and returns it. It does not change the gate.

Call relations: The tests use this to check the visible effect of calling close or shutdown. Production code does not use it because it is compiled only during testing.

fn inflight_count(&self) -> usize

Purpose: Reports how many RPC handlers are currently tracked as in progress. This helper exists only for tests.

Data flow: It asks the task tracker for its current length and returns that number. It does not start, stop, or change any work.

Call relations: The tests use this to prove that run adds work to the tracker before the handler body continues, and that the count returns to zero after the handler finishes.

Call graph: 1 external calls (len).

fn default() -> Self

Purpose: Provides Rust’s standard default construction behavior for this gate. A default gate is the same as a newly created open gate.

Data flow: Nothing is passed in. It delegates to ConnectionRpcGate::new and returns the resulting open gate.

Call relations: This fits the gate into Rust APIs that expect a Default value. Rather than keeping separate setup logic, it relies on new so both construction paths stay identical.

Call graph: 1 external calls (new).

async fn run_executes_while_open()

Purpose: Checks that an open gate actually runs the async work passed to run. This protects the normal successful path.

Data flow: The test starts with a new open gate and an atomic boolean set to false. It passes async work that flips the boolean to true. After run finishes, the test reads the boolean and expects it to be true.

Call relations: This test exercises the basic relationship between new and run: a freshly created gate should accept work. It uses shared atomic state so the test can see whether the handler body ran.

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

async fn run_drops_future_without_polling_after_close()

Purpose: Checks that once the gate is closed, later work does not start at all. This matters because merely creating async work is different from polling it, which is what actually begins running it.

Data flow: The test creates a gate, closes it, and prepares async work that would flip an atomic boolean if it ran. It calls run with that work. The expected result is that the boolean stays false and the gate reports that it is not accepting.

Call relations: This test connects close, run, and is_accepting. It proves that closing the gate affects future run calls immediately, instead of letting a late handler sneak through.

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

async fn close_returns_while_started_run_remains_active()

Purpose: Checks that close stops new work but does not wait for or cancel work that already started. This confirms the difference between closing the door and waiting for everyone to leave.

Data flow: The test starts a handler that signals when it has begun, then waits on a one-shot message before finishing. After the handler has started, the test calls close. It expects the gate to be closed and the in-flight count to still be one. Then it sends the finish message, waits for the run task to complete, and shuts the gate down cleanly.

Call relations: This test uses new, run, close, inflight_count, and shutdown together. It shows that close is a non-blocking step, while the later cleanup can still wait for the active task.

Call graph: calls 1 internal fn (new); 6 external calls (clone, new, assert!, assert_eq!, channel, spawn).

async fn shutdown_waits_for_started_run_to_finish()

Purpose: Checks that shutdown waits for already-started work instead of returning too early. This protects graceful connection cleanup.

Data flow: The test starts a handler that signals it has begun and then waits for permission to finish. It starts shutdown in another task and uses a short timeout to confirm shutdown does not complete while the handler is still waiting. After sending the finish signal, it waits for the running task and confirms the in-flight count can reach zero.

Call relations: This test focuses on the relationship between run and shutdown. Because shutdown calls close and then waits on the tracker, the test verifies that the tracker token held by run really keeps shutdown pending.

Call graph: calls 1 internal fn (new); 7 external calls (clone, new, from_millis, assert_eq!, channel, spawn, timeout).

async fn shutdown_drops_late_runs_while_waiting_for_inflight_work()

Purpose: Checks the tricky case where shutdown has begun but one earlier handler is still running. Late work should be rejected during that waiting period.

Data flow: The test starts one handler and holds it open. It starts shutdown and confirms with a timeout that shutdown is waiting. While shutdown is waiting, it calls run with new async work that would flip a boolean if it ran. The boolean must stay false. Then the original handler is allowed to finish, and the final in-flight count should be zero.

Call relations: This test ties together run, shutdown, and the closed accepting flag. It proves that once shutdown has closed the gate, the system both waits for old work and rejects new work at the same time.

Call graph: calls 1 internal fn (new); 9 external calls (clone, new, new, from_millis, assert!, assert_eq!, channel, spawn, timeout).

async fn run_is_counted_before_handler_body_continues()

Purpose: Checks that a handler is counted as in flight before its body proceeds far enough to signal entry. This avoids a race where shutdown might miss work that has just started.

Data flow: The test starts a handler that sends an entered signal and then waits. After receiving the entered signal, the test checks the in-flight count and expects it to be one. It then lets the handler continue, waits for it to finish, and expects the count to return to zero.

Call relations: This test examines the ordering inside run: the tracker token must be acquired before the handler body continues. That ordering is what makes shutdown reliable when work starts near the same time as closing.

Call graph: calls 1 internal fn (new); 5 external calls (clone, new, assert_eq!, channel, spawn).

fn new() -> Self

Purpose: Creates an empty tracker for connection cleanup tasks. The server uses this when it starts the main run flow so it has one place to collect later cleanup jobs.

Data flow: Nothing is passed in. The function creates a fresh empty task collection and wraps it in ConnectionCleanupTasks. The result is a ready-to-use cleanup tracker with no jobs inside yet.

Call relations: The main server setup, run_main_with_transport_options, calls this when preparing to run. After that, other parts of the server can add cleanup jobs to the tracker and wait for them through its other methods.

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

fn spawn(&mut self, future: impl Future<Output = ()> + Send + 'static)

Purpose: Adds a new cleanup job to the background task collection. Someone uses this when cleanup should happen without blocking the main server work.

Data flow: It receives a future, which is a piece of asynchronous work that will eventually finish. It gives that future to Tokio's task system, which starts running it in the background, and stores it in the internal collection so the server can later observe or cancel it. It returns nothing directly.

Call relations: This is the entry point for putting cleanup work under this file's supervision. Once a job has been spawned here, reap_next or drain can later collect its result, and abort can cancel it if shutdown happens first.

Call graph: 1 external calls (spawn).

async fn reap_next(&mut self)

Purpose: Waits for one cleanup task to finish and records whether it ended normally or failed. It is designed for a main loop that wants to periodically collect completed cleanup work without draining everything at once.

Data flow: It reads the internal task collection. If there are no tasks, it waits forever, which means it produces no event until some other branch of the surrounding program does something. If there is at least one task, it waits until one finishes, then passes that task's result to log_cleanup_result. It does not return a value, but it removes the finished task from the collection.

Call relations: This method calls log_cleanup_result after Tokio reports that a cleanup task has completed. In the bigger flow, it acts like the server's broom: each time the run loop is ready to collect one finished cleanup job, this method picks it up and hands the outcome to the logging helper.

Call graph: calls 1 internal fn (log_cleanup_result); 2 external calls (is_empty, join_next).

async fn drain(&mut self)

Purpose: Waits for every remaining cleanup task to finish. This is useful during orderly shutdown, when the server wants to give cleanup work a chance to complete before exiting.

Data flow: It repeatedly asks the internal task collection for the next finished task. Each result is sent to log_cleanup_result so failures are not hidden. The loop ends when no cleanup tasks remain. It returns nothing, but the collection is empty afterward.

Call relations: This method uses log_cleanup_result for each completed task, just like reap_next, but keeps going until the collection is empty. It is the finishing step when the server wants to clear all outstanding cleanup jobs rather than collect just one.

Call graph: calls 1 internal fn (log_cleanup_result); 1 external calls (join_next).

fn abort(&mut self)

Purpose: Cancels all cleanup tasks that are still running. This is used when the server needs to stop quickly and should not wait for background cleanup to finish.

Data flow: It reads the internal task collection and tells Tokio to abort every task in it. The tasks are marked for cancellation. The function returns nothing; later, if those cancelled tasks are collected, their cancellation is treated as expected rather than as a warning.

Call relations: This method is the emergency stop for the cleanup tracker. After tasks have been added with spawn, shutdown code can call abort to cancel them all, and log_cleanup_result will avoid warning about those intentional cancellations when their results are later observed.

Call graph: 1 external calls (abort_all).

fn log_cleanup_result(result: Result<(), JoinError>)

Purpose: Decides whether a finished cleanup task needs a warning in the logs. It keeps normal completions and intentional cancellations quiet, but reports unexpected task failures.

Data flow: It receives the result of a background cleanup task. If the result is successful, it does nothing. If the task ended with an error, it checks whether that error was just cancellation; cancelled tasks are ignored, while other errors are written as warnings. It returns nothing.

Call relations: reap_next and drain call this after receiving completed task results from Tokio. It is the shared checkpoint that turns raw task outcomes into useful server logs, so the rest of the cleanup code does not repeat the same error-checking rules.

Call graph: called by 2 (drain, reap_next); 1 external calls (warn!).

async fn shutdown_live_agent(&self, agent_id: ThreadId) -> CodexResult<String>

Purpose: Stops one live agent without marking its saved spawn relationship as closed. It is used when the system needs the worker gone now, while leaving the separate “was this explicitly closed?” record unchanged.

Data flow: It receives an agent thread id. It first upgrades the control handle into live shared state; if that fails, the error is returned. If the thread is found, it makes sure the session’s pending rollout data exists and is flushed to storage, checks whether the agent is already shut down, and otherwise sends it a shutdown operation. It then waits for the thread to finish. If the thread was not found, it still tries to send a shutdown operation by id. At the end it removes the thread from tracking, forgets related residency information, releases spawned-thread bookkeeping, and returns either the shutdown result string or an error.

Call relations: This is the basic single-agent stop action. AgentControl::shutdown_agent_tree calls it first for the requested agent and then for each descendant, so the tree-level shutdown can reuse the same careful cleanup path for every live worker.

Call graph: called by 1 (shutdown_agent_tree); 2 external calls (new, matches!).

async fn close_agent(&self, agent_id: ThreadId) -> CodexResult<String>

Purpose: Marks an agent as explicitly closed in saved state, then shuts down that agent and any live descendants beneath it. This is the stronger form of stopping: it records the user’s intent, not just the fact that the process should stop.

Data flow: It receives an agent thread id. It checks whether the system already knows metadata for that agent, then tries to inspect the live thread. If the thread is live and has access to the state database, it writes the spawn-edge status as Closed. If the thread is gone but the agent is still known, it tries to write the same Closed mark through the broader state database; failure there becomes a fatal error because the saved close decision would be lost. Other inspection failures are logged as warnings. After this persistence step, it calls the tree shutdown path. If a known stale agent is already missing or internally dead, it treats that as a harmless successful close.

Call relations: This is the higher-level close operation. It does the persistent “closed” bookkeeping itself, logs or returns errors when that bookkeeping cannot be trusted, and then hands the actual stopping work to AgentControl::shutdown_agent_tree.

Call graph: calls 1 internal fn (shutdown_agent_tree); 5 external calls (pin, new, format!, Fatal, warn!).

async fn shutdown_agent_tree(&self, agent_id: ThreadId) -> CodexResult<String>

Purpose: Stops one agent plus any live child agents that can be reached from the current in-memory spawn tree. It is useful when stopping a parent should also clean up workers that were started under it.

Data flow: It receives the root agent thread id. It asks for the list of live descendant thread ids, then shuts down the root agent and saves that result. After that it walks through each descendant and shuts it down too. Missing or already-dead descendants are ignored, because they no longer need stopping. Any other descendant shutdown error stops the process and is returned. If descendant cleanup succeeds, the function returns the original root agent’s shutdown result.

Call relations: AgentControl::close_agent calls this after it has recorded the close status. This function coordinates the multi-agent shutdown, while AgentControl::shutdown_live_agent performs the actual per-agent flush, stop request, wait, and cleanup.

Call graph: calls 1 internal fn (shutdown_live_agent); called by 1 (close_agent).