Exec-server, sandbox, and remote transport harnesses

fn current_test_binary_helper_paths() -> anyhow::Result<(PathBuf, Option<PathBuf>)>

Purpose: This function tells tests which executable path to use when they need to launch helper programs. On Linux, it also supplies the path for the sandbox helper, because sandboxing is part of the process-launch tests there.

Data flow: It reads the path of the currently running test executable. If the operating system is Linux, it looks for a sandbox-helper path prepared by the dispatch setup; if none is available, it falls back to the current test executable. It returns the current executable path plus an optional sandbox executable path.

Call relations: Higher-level tests call this when they are about to start processes that need helper binaries. It is used by tests that check delayed output capture and encrypted exec-server routing, so those tests can launch the right helper without knowing how the test binary dispatch was arranged.

Call graph: called by 2 (assert_exec_process_retains_output_after_exit_until_streams_close, remote_environment_routes_encrypted_exec_server_rpc); 2 external calls (cfg!, current_exe).

fn maybe_run_delayed_output_after_exit_from_test_binary()

Purpose: This function checks whether the current test binary was launched in one of the special delayed-output modes. If so, it stops acting like a normal test process and runs the tiny helper behavior needed for that test.

Data flow: It reads the command-line arguments. If the first real argument asks for the delayed-output parent mode, it reads a release path and starts the parent helper. If it asks for the child mode, it reads the same kind of path and starts the child helper. If the argument is anything else or missing, it does nothing.

Call relations: It is called during the test binary’s early setup, before normal test behavior matters. It hands argument parsing for the release path to next_release_path_arg, then hands execution to either run_delayed_output_after_exit_parent or run_delayed_output_after_exit_child depending on the requested mode.

Call graph: calls 3 internal fn (next_release_path_arg, run_delayed_output_after_exit_child, run_delayed_output_after_exit_parent); 1 external calls (args).

fn next_release_path_arg(mut args: impl Iterator<Item = String>) -> PathBuf

Purpose: This function reads and validates the one path argument required by the delayed-output helper modes. It exists so the parent and child modes both enforce the same simple command-line shape.

Data flow: It receives the remaining command-line arguments. It expects exactly one value, turns that string into a filesystem path, and returns it. If the value is missing or there is anything extra, it prints a clear error and exits the process with failure.

Call relations: It is used only by maybe_run_delayed_output_after_exit_from_test_binary after that function has recognized one of the delayed-output commands. It prepares the release path that is then passed into the parent or child helper.

Call graph: called by 1 (maybe_run_delayed_output_after_exit_from_test_binary); 4 external calls (next, from, eprintln!, exit).

fn run_delayed_output_after_exit_parent(release_path: &Path)

Purpose: This function starts the delayed-output child process and then exits immediately. It is used to simulate a program whose parent finishes before all output from its process group has arrived.

Data flow: It receives a release path. It finds the current test executable, launches that same executable again in child mode with the release path, gives the child no standard input, and then exits successfully. If it cannot find or start the child process, it prints the error and exits with failure.

Call relations: It is called by maybe_run_delayed_output_after_exit_from_test_binary when the test binary is invoked in delayed-output parent mode. Its job is to create the child process that will later run run_delayed_output_after_exit_child, while making the original parent disappear quickly.

Call graph: called by 1 (maybe_run_delayed_output_after_exit_from_test_binary); 5 external calls (null, new, current_exe, eprintln!, exit).

fn run_delayed_output_after_exit_child(release_path: &Path)

Purpose: This function waits for permission to print late output, then writes a test message to standard output. It helps verify that the exec system does not lose output that arrives after the original parent process has exited.

Data flow: It receives a release path. It checks for that path repeatedly for up to about ten seconds. Once the path exists, it writes late output after exit to standard output, flushes the output so it is really sent, and exits successfully. If writing fails or the path never appears, it prints an error and exits with failure.

Call relations: It is reached through maybe_run_delayed_output_after_exit_from_test_binary when the current process was launched in child mode. The parent helper creates this child, and an outside test controls when the child is released by creating the watched path.

Call graph: called by 1 (maybe_run_delayed_output_after_exit_from_test_binary); 7 external calls (from_millis, exists, eprintln!, stdout, exit, sleep, writeln!).

fn maybe_run_exec_server_from_test_binary(guard: Option<&TestBinaryDispatchGuard>)

Purpose: This function lets the test executable turn into an exec server process when launched with the right arguments. That allows integration tests to start a real server without needing a separately installed exec-server binary.

Data flow: It reads the command-line arguments and only continues for exec-server --listen <url>. It finds the current executable, builds the runtime paths the server needs, creates a Tokio asynchronous runtime, and runs codex_exec_server::run_main using the listen URL. It exits the process with code 0 on success or 1 on failure, printing useful errors along the way.

Call relations: It is called during early test binary setup after dispatch has been configured. It uses linux_sandbox_exe to decide which sandbox helper path to give the server, then hands off to the real exec-server entry function codex_exec_server::run_main.

Call graph: calls 2 internal fn (new, linux_sandbox_exe); 6 external calls (run_main, args, current_exe, eprintln!, exit, new_multi_thread).

fn linux_sandbox_exe(
    guard: Option<&TestBinaryDispatchGuard>,
    current_exe: &std::path::Path,
) -> Option<PathBuf>

Purpose: This function chooses the executable path to use for the Linux sandbox helper during tests. On non-Linux systems it returns nothing, because that sandbox helper is not used there.

Data flow: It receives the optional test dispatch guard and the current executable path. On Linux, it first tries to use the sandbox path recorded by the guard; if that is not available, it uses the current test executable as the fallback helper. On other operating systems, it ignores both inputs and returns no path.

Call relations: It is called by maybe_run_exec_server_from_test_binary while preparing runtime paths for a test exec server. Its result is folded into ExecServerRuntimePaths, which tells the server where to find the helper programs it may need when executing commands.

Call graph: called by 1 (maybe_run_exec_server_from_test_binary).

fn drop(&mut self)

Purpose: This is the safety cleanup for the test harness. If a test ends without explicitly shutting down the server, it asks the child exec-server process to stop so it does not keep running in the background.

Data flow: When the harness object is about to be destroyed, it already contains a running child process. The function sends a kill request to that process and ignores any error, because cleanup during drop should not cause a second failure while the test is ending. Nothing is returned.

Call relations: This runs automatically when an ExecServerHarness goes out of scope. It uses the child process kill operation directly, and it acts as the fallback cleanup path alongside the more explicit ExecServerHarness::shutdown method.

Call graph: 1 external calls (start_kill).

fn test_codex_helper_paths() -> anyhow::Result<TestCodexHelperPaths>

Purpose: This finds the helper executables that tests need in order to start the real Codex server process. It packages those paths into a small struct so the rest of the harness can use them consistently.

Data flow: It asks shared test code for the current test helper binary paths. It then stores the main Codex executable path and, if available, the Linux sandbox helper path in TestCodexHelperPaths. The result is either those paths or an error explaining why they could not be found.

Call relations: The server startup path calls this from exec_server_with_env before spawning the child process. Other test helpers, such as create_file_system_context, also use it when they need the same executable locations.

Call graph: called by 2 (exec_server_with_env, create_file_system_context); 1 external calls (current_test_binary_helper_paths).

async fn exec_server() -> anyhow::Result<ExecServerHarness>

Purpose: This is the simple default way for tests to start an exec-server. It starts the server with no extra environment variables.

Data flow: It begins with an empty set of environment overrides. It passes that empty set into exec_server_with_env, which does the real startup work. It returns a ready-to-use ExecServerHarness or an error if startup or connection fails.

Call relations: Many integration tests call this when they need a normal server instance. It is a convenience wrapper over exec_server_with_env, so tests only use the more detailed function when they need to customize the server’s environment.

Call graph: calls 1 internal fn (exec_server_with_env); called by 24 (create_process_context, completed_streams_release_handle_capacity, file_reads_reject_fifo_without_waiting_for_a_writer, file_reads_reject_named_pipes, open_enforces_the_per_connection_limit_and_close_releases_capacity, open_rejects_handle_ids_longer_than_32_bytes, read_block_supports_non_sequential_offsets_and_lengths, stream_keeps_reading_the_open_file_after_path_replacement, stream_rejects_platform_sandbox, stream_stops_after_an_exact_block_boundary (+14 more)).

async fn exec_server_with_env(env: I) -> anyhow::Result<ExecServerHarness>

Purpose: This starts a real exec-server process for a test, optionally adding custom environment variables. It returns a harness that is already connected to the server over WebSocket.

Data flow: It receives environment variable pairs from the caller. It finds the test helper binary, creates a temporary CODEX_HOME, builds a child process command for exec-server --listen ws://127.0.0.1:0, captures stdout, and starts the process. It reads the actual listening URL from stdout, connects to that WebSocket address, and returns an ExecServerHarness containing the temp directory, process, URL, WebSocket connection, and first request id.

Call relations: This is the main setup function behind exec_server, and specialized tests call it directly when they need custom environment settings. During setup it calls test_codex_helper_paths, read_listen_url_from_stdout, and connect_websocket_when_ready in that order.

Call graph: calls 3 internal fn (connect_websocket_when_ready, read_listen_url_from_stdout, test_codex_helper_paths); called by 2 (exec_server, sandboxed_file_system_helper_finds_bwrap_on_preserved_path); 5 external calls (inherit, null, piped, new, new).

fn websocket_url(&self) -> &str

Purpose: This lets a test inspect the WebSocket address that the server chose. It is useful when a test needs to open another connection or check connection behavior.

Data flow: It reads the stored WebSocket URL string from the harness and returns it as borrowed text. It does not change the harness or talk to the server.

Call relations: Tests call this as a small accessor after the harness has been created by exec_server or exec_server_with_env. It does not call other helper functions.

async fn disconnect_websocket(&mut self) -> anyhow::Result<()>

Purpose: This closes the harness’s current WebSocket connection to the server. Tests use it to check how the server reacts when a client disconnects.

Data flow: It starts with the open WebSocket stored in the harness. It sends a normal close frame to the server and returns success if that close request was sent cleanly, or an error if the WebSocket operation failed.

Call relations: This is used during tests that need to simulate a dropped or closed client connection. A test can later call ExecServerHarness::reconnect_websocket to attach the same harness to the same server again.

Call graph: 1 external calls (close).

async fn reconnect_websocket(&mut self) -> anyhow::Result<()>

Purpose: This opens a new WebSocket connection to the same server URL after the current connection has been closed or replaced. It lets tests continue using the same server process across reconnect scenarios.

Data flow: It reads the saved WebSocket URL from the harness. It calls the retrying connection helper, then replaces the harness’s WebSocket field with the newly connected stream. It returns success or a connection error.

Call relations: Tests call this after disconnecting or after intentionally disturbing the connection. It relies on connect_websocket_when_ready, the same retry helper used during initial server startup.

Call graph: calls 1 internal fn (connect_websocket_when_ready).

async fn send_request(
        &mut self,
        method: &str,
        params: serde_json::Value,
    ) -> anyhow::Result<RequestId>

Purpose: This sends a JSON-RPC request to the server and gives the caller the request id that was used. Tests use that id later to match responses back to the request they sent.

Data flow: It receives a method name and JSON parameters. It creates the next integer request id, increments the harness’s counter for future requests, wraps the method and parameters into a JSON-RPC request message, and sends it over the WebSocket. It returns the request id if sending worked.

Call relations: Higher-level test setup such as initialize_exec_server calls this to ask the server to do something. Internally it delegates the actual JSON encoding and WebSocket send to ExecServerHarness::send_message.

Call graph: calls 1 internal fn (send_message); called by 1 (initialize_exec_server); 2 external calls (Request, Integer).

async fn send_notification(
        &mut self,
        method: &str,
        params: serde_json::Value,
    ) -> anyhow::Result<()>

Purpose: This sends a JSON-RPC notification to the server. A notification is like a one-way message: it has a method and parameters, but no request id and no expected direct response.

Data flow: It receives a method name and JSON parameters. It wraps them in a JSON-RPC notification message and sends that message through the harness’s WebSocket. The output is just success or an error from sending.

Call relations: Test setup code such as initialize_exec_server uses this when it needs to inform the server of something without tracking a reply. Like request sending, it passes the final send work to ExecServerHarness::send_message.

Call graph: calls 1 internal fn (send_message); called by 1 (initialize_exec_server); 1 external calls (Notification).

async fn send_raw_text(&mut self, text: &str) -> anyhow::Result<()>

Purpose: This sends an exact text WebSocket frame without wrapping it as JSON-RPC first. Tests use it to check server behavior for malformed or unusual client input.

Data flow: It receives a text string from the test. It turns that string into a WebSocket text message and sends it directly over the current connection. It returns success or the WebSocket send error.

Call relations: This bypasses the normal send_message path on purpose. It is for lower-level protocol tests where the caller wants full control over what bytes the server sees.

Call graph: 2 external calls (send, Text).

async fn send_raw_binary(&mut self, bytes: Vec<u8>) -> anyhow::Result<()>

Purpose: This sends an exact binary WebSocket frame to the server. It is useful for tests that need to send non-text or intentionally invalid data.

Data flow: It receives a vector of bytes. It turns those bytes into a WebSocket binary message and sends it through the current connection. It returns success or a send error.

Call relations: Like ExecServerHarness::send_raw_text, this avoids JSON-RPC formatting. It supports tests that focus on protocol robustness rather than normal request and response behavior.

Call graph: 2 external calls (send, Binary).

async fn next_event(&mut self) -> anyhow::Result<JSONRPCMessage>

Purpose: This waits for the next JSON-RPC message from the server using the standard test timeout. It prevents tests from hanging forever if the server never sends anything.

Data flow: It reads from the harness’s WebSocket connection. It waits up to the default event timeout, decodes the next text or binary frame as JSON-RPC, and returns that message. If the timeout expires, the connection closes, or the data cannot be decoded, it returns an error.

Call relations: Helpers such as collect_response_body_deltas call this when they want the next event regardless of its contents. It is a thin wrapper around ExecServerHarness::next_event_with_timeout with the usual timeout value.

Call graph: calls 1 internal fn (next_event_with_timeout); called by 1 (collect_response_body_deltas).

async fn wait_for_event(
        &mut self,
        mut predicate: F,
    ) -> anyhow::Result<JSONRPCMessage>

Purpose: This keeps reading server messages until one matches a condition chosen by the test. It is useful because servers may send several events, and a test often only cares about one specific response or error.

Data flow: It receives a predicate, which is a small yes-or-no test function supplied by the caller. Until the overall timeout expires, it reads the next event with the remaining time and checks it with the predicate. It returns the first matching message, or an error if no matching message arrives in time.

Call relations: Higher-level helpers such as wait_for_response and wait_for_error_response use this to wait for particular server replies. It repeatedly calls ExecServerHarness::next_event_with_timeout, shrinking the allowed time on each loop so the total wait remains bounded.

Call graph: calls 1 internal fn (next_event_with_timeout); called by 2 (wait_for_error_response, wait_for_response); 2 external calls (now, anyhow!).

async fn shutdown(&mut self) -> anyhow::Result<()>

Purpose: This explicitly stops the child exec-server process and waits for it to exit. Tests can call it when they want controlled teardown instead of relying only on automatic cleanup.

Data flow: It sends a kill request to the stored child process. Then it waits for the process to finish, but only up to the connection timeout. It returns success when the process exits, or an error if killing or waiting fails or takes too long.

Call relations: This is the deliberate teardown counterpart to the automatic ExecServerHarness::drop cleanup. It talks directly to the child process and uses a timeout so a stuck server does not stall the whole test run.

Call graph: 3 external calls (start_kill, wait, timeout).

async fn send_message(&mut self, message: JSONRPCMessage) -> anyhow::Result<()>

Purpose: This is the shared low-level sender for normal JSON-RPC messages. It turns a structured request or notification into JSON text and puts it on the WebSocket.

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

Call relations: ExecServerHarness::send_request and ExecServerHarness::send_notification both use this after they build the right kind of JSON-RPC message. Keeping this in one place means both message types are encoded and sent the same way.

Call graph: called by 2 (send_notification, send_request); 3 external calls (send, to_string, Text).

async fn next_event_with_timeout(
        &mut self,
        timeout_duration: Duration,
    ) -> anyhow::Result<JSONRPCMessage>

Purpose: This reads the next meaningful server message, with a caller-chosen timeout. It understands basic WebSocket frame types and converts text or binary JSON into a JSONRPCMessage.

Data flow: It receives a timeout duration and reads frames from the harness’s WebSocket. If it gets text, it parses the text as JSON-RPC; if it gets binary data, it parses the bytes as JSON-RPC. It ignores ping and pong frames, reports an error on close, and reports an error if no usable event arrives before the timeout.

Call relations: ExecServerHarness::next_event uses this with the standard timeout, while ExecServerHarness::wait_for_event uses it with the remaining time in a larger wait. It is the central receive-and-decode function for normal server events.

Call graph: called by 2 (next_event, wait_for_event); 5 external calls (next, anyhow!, from_slice, from_str, timeout).

async fn connect_websocket_when_ready(
    websocket_url: &str,
) -> anyhow::Result<(
    tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>,
    tokio_tungst

Purpose: This connects to the server’s WebSocket address, allowing for the short delay between process startup and the server actually accepting connections. It makes startup tests less flaky.

Data flow: It receives a WebSocket URL. It repeatedly tries to connect until it succeeds, the overall connection timeout expires, or it hits an error other than temporary connection refusal. On success it returns the connected WebSocket stream and handshake response; on failure it returns the connection error.

Call relations: exec_server_with_env calls this after reading the server’s listening URL, and ExecServerHarness::reconnect_websocket calls it when a test needs a fresh connection. It hands the ready WebSocket stream back to the harness.

Call graph: called by 2 (reconnect_websocket, exec_server_with_env); 4 external calls (now, matches!, sleep, connect_async).

async fn read_listen_url_from_stdout(child: &mut Child) -> anyhow::Result<String>

Purpose: This waits for the newly started server to print the WebSocket URL it is listening on. That URL is needed because the server is started with port 0, which asks the operating system to choose a free port.

Data flow: It receives the child process object, takes its captured stdout, and reads lines until the timeout expires. It trims each line and returns the first one that starts with ws://. If stdout is missing, closes too early, or never prints a URL in time, it returns an error.

Call relations: exec_server_with_env calls this immediately after spawning the server process. The returned URL is then passed to connect_websocket_when_ready so the harness can open the WebSocket connection.

Call graph: called by 1 (exec_server_with_env); 4 external calls (new, now, anyhow!, timeout).

fn parse_listen_url_accepts_default_websocket_url()

Purpose: This test proves that the built-in default listen URL is valid and becomes the expected WebSocket listening address. It guards against accidentally changing the default into something the server cannot parse.

Data flow: It starts with DEFAULT_LISTEN_URL, passes that text into parse_listen_url, and expects a successful result. The parsed result is then compared with the expected WebSocket transport bound to 127.0.0.1:0, where port 0 means the operating system may choose an available port.

Call relations: This is one of the direct parser checks in the file. It calls parse_listen_url and uses an equality assertion to confirm the parser returns the exact transport choice the rest of the server startup code would rely on.

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

fn parse_listen_url_accepts_stdio()

Purpose: This test checks that the plain word stdio is accepted as a request to communicate through standard input and output. That keeps the command-line spelling simple and stable for users or tools that launch the server this way.

Data flow: It gives the text stdio to parse_listen_url. The expected before-to-after change is from a user-written string to the internal value ExecServerListenTransport::Stdio; the test fails if parsing returns an error or a different transport.

Call relations: Like the other parser tests, it focuses on one supported input form. It calls parse_listen_url directly and then checks the returned transport with an equality assertion.

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

fn parse_listen_url_accepts_stdio_url()

Purpose: This test checks that stdio:// is also accepted as a stdio listen setting. It allows stdio to be written in a URL-like style, matching the shape of settings such as ws://....

Data flow: It sends the string stdio:// into parse_listen_url. The parser should turn that string into the same internal stdio transport value as the shorter stdio spelling.

Call relations: This test complements parse_listen_url_accepts_stdio by covering the alternate accepted spelling. It calls the parser and uses an assertion to make sure both forms lead to the same server transport choice.

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

async fn stdio_listen_transport_serves_initialize()

Purpose: This asynchronous test proves that the stdio transport can perform the server's opening handshake with a client. It checks that the server reads an initialize request, sends back a usable session id, accepts the follow-up initialized notification, and exits cleanly when the client disconnects.

Data flow: The test begins by parsing stdio and building two in-memory communication streams: one direction for client-to-server messages and one for server-to-client messages. It starts the stdio server task with test runtime paths, writes a JSON-RPC initialize request into the client side, reads one response line back, decodes it, and confirms the response id matches and the returned session id is not empty. It then writes an initialized notification, closes the client streams, and waits for the server task to finish without error.

Call relations: This is the main end-to-end transport test in the file. It calls test_runtime_paths to provide the server with safe paths for the test run, and it calls write_jsonrpc_line twice so the fake client sends correctly formatted one-line JSON-RPC messages. It also exercises the real run_stdio_connection_with_io path, so failures here point to problems in the stdio connection flow rather than only in URL parsing.

Call graph: calls 2 internal fn (test_runtime_paths, write_jsonrpc_line); 16 external calls (new, from_secs, Notification, Request, Integer, assert!, assert_eq!, panic!, from_str, from_value (+6 more)).

fn parse_listen_url_accepts_websocket_url()

Purpose: This test confirms that a normal WebSocket listen URL with a numeric IP address and port is accepted. It protects the common network-listening form of the server configuration.

Data flow: It passes ws://127.0.0.1:1234 into parse_listen_url. The parser should produce a WebSocket transport containing the socket address 127.0.0.1:1234, and the test compares the actual result to that expected value.

Call relations: This test is part of the parser coverage for accepted inputs. It calls parse_listen_url directly and verifies the returned WebSocket address is preserved exactly.

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

fn parse_listen_url_rejects_invalid_websocket_url()

Purpose: This test makes sure a WebSocket URL using a hostname, such as localhost, is rejected when the server expects a concrete IP address. That keeps listen addresses unambiguous and prevents later binding surprises.

Data flow: It gives ws://localhost:1234 to parse_listen_url and expects an error instead of a transport. The error text is then compared with the exact message users should see, explaining that the expected format is ws://IP:PORT.

Call relations: This is a negative parser test: it checks that bad input is not silently accepted. It calls parse_listen_url, expects failure, and uses an equality assertion to lock down the human-readable error message.

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

fn parse_listen_url_rejects_unsupported_url()

Purpose: This test checks that unsupported URL schemes, such as http://, are rejected with a clear explanation. It prevents users from thinking the exec server can listen over transports it does not implement.

Data flow: It passes http://127.0.0.1:1234 into parse_listen_url and expects parsing to fail. The resulting error string is compared with the expected message, which tells the user to use either ws://IP:PORT or stdio.

Call relations: This negative test sits alongside the invalid WebSocket test. It calls parse_listen_url directly and confirms both the rejection and the wording that would be shown to someone configuring the server.

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

async fn write_jsonrpc_line(writer: &mut tokio::io::DuplexStream, message: &JSONRPCMessage)

Purpose: This helper writes one JSON-RPC message to an in-memory stream in the same line-based format the stdio server expects. It keeps the main stdio test focused on the handshake instead of repeating message-writing details.

Data flow: It receives a writable duplex stream and a JSON-RPC message value. It turns the message into JSON bytes, writes those bytes to the stream, then writes a newline byte so the server can read the message as one complete line. It does not return a message; its effect is that the fake client has sent data to the fake server.

Call relations: It is called by stdio_listen_transport_serves_initialize when that test sends the initialize request and later the initialized notification. Internally it relies on JSON serialization and asynchronous stream writes so the test uses the same basic message shape as a real stdio client.

Call graph: called by 1 (stdio_listen_transport_serves_initialize); 2 external calls (write_all, to_vec).

fn test_runtime_paths() -> ExecServerRuntimePaths

Purpose: This helper builds the runtime path information needed to start the server inside the test. It supplies the current test executable as the main executable path and leaves the optional Linux sandbox executable unset.

Data flow: It reads the path of the currently running executable from the environment, passes that path plus None for the sandbox executable into ExecServerRuntimePaths::new, and returns the validated runtime paths. If the path cannot be read or validated, the test fails immediately.

Call relations: It is called by stdio_listen_transport_serves_initialize just before starting run_stdio_connection_with_io. Its job is to provide enough realistic setup data for the stdio server task to start without making the test depend on an external sandbox binary.

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

async fn exec_server_accepts_initialize() -> anyhow::Result<()>

Purpose: This test proves that the exec server accepts an initialize request and returns a usable initialization response. It is meant to catch breakage in the first step a client takes when connecting to the server.

Data flow: The test starts with no running server, then creates a test exec server. It sends an initialize request containing a client name and no session to resume. The server returns an event; the test expects that event to be a JSON-RPC response, checks that its ID matches the request that was sent, converts the response body into an InitializeResponse, and verifies that the session ID is a valid UUID. At the end, it shuts the server down and returns success if all checks passed.

Call relations: This function is run by the async Rust test runner. During the test, it asks the shared test helper exec_server to start a server, uses serialization helpers to turn request data into JSON and response JSON back into typed Rust data, uses an assertion to confirm the response belongs to the request, and uses UUID parsing as a final sanity check on the server-created session ID. If the next message is not a response, the test deliberately fails immediately.

Call graph: calls 1 internal fn (exec_server); 5 external calls (parse_str, assert_eq!, panic!, from_value, to_value).

async fn exec_server_serves_readyz_alongside_websocket_endpoint() -> anyhow::Result<()>

Purpose: This test verifies that the exec server serves a basic HTTP readiness check at /readyz while also offering its WebSocket endpoint. Someone would rely on this to know that health checks and WebSocket service can coexist on the same test server.

Data flow: It starts a temporary exec server, reads the server's WebSocket URL, and turns that into an HTTP base address by removing the ws:// prefix. It then sends an HTTP GET request to /readyz, checks that the response status is OK, and finally shuts the server down.

Call relations: During the test, it calls the shared exec_server helper to start the server. It then uses format! to build the readiness URL, reqwest::get to make the HTTP request, and assert_eq! to confirm the server answered with the expected OK status.

Call graph: calls 1 internal fn (exec_server); 3 external calls (assert_eq!, format!, get).

async fn remote_environment_fetches_info_from_exec_server() -> anyhow::Result<()>

Purpose: This test verifies that a test Environment connected to the exec server behaves as a remote environment and returns the same environment information as the local test environment. It protects the contract that remote execution should report consistent basic facts.

Data flow: It starts a temporary exec server and builds an Environment using the server's WebSocket URL. It checks that this environment identifies itself as remote, asks it for its information, asks a default local test environment for the same information, compares the two results, and then shuts the server down.

Call relations: The test begins by calling the shared exec_server helper, then uses Environment::create_for_tests to make a remote environment connected to that server. It uses Environment::default_for_tests as the local comparison point, and relies on assertions to confirm both that the environment is remote and that the remote and local information match.

Call graph: calls 3 internal fn (create_for_tests, default_for_tests, exec_server); 2 external calls (assert!, assert_eq!).

async fn exec_server_reports_malformed_websocket_json_and_keeps_running() -> anyhow::Result<()>

Purpose: This test makes sure one bad WebSocket message does not poison the whole connection or crash the server. It sends invalid JSON, expects a proper error response, then sends a normal initialize request to prove the server is still usable.

Data flow: The test starts a fresh exec server, then sends the raw text not-json into its WebSocket. It waits until the server sends back a JSON-RPC error, checks that the error has the expected id, code, and message prefix, then sends a valid initialize request. The server replies with initialize data, and the test parses the returned session id as a UUID to confirm it looks real before shutting the server down.

Call relations: This test begins by calling the shared test helper exec_server to launch a server instance. It then uses the test server’s WebSocket helper methods to send raw input and wait for protocol messages. After the malformed-message checks, it hands a valid initialize payload through JSON serialization and checks the response by deserializing it back into InitializeResponse.

Call graph: calls 1 internal fn (exec_server); 6 external calls (parse_str, assert!, assert_eq!, panic!, from_value, to_value).

async fn exec_server_accepts_binary_websocket_json() -> anyhow::Result<()>

Purpose: This test checks that the exec server accepts JSON-RPC messages sent as binary WebSocket frames, not only as text frames. That matters because different WebSocket clients may choose either form even when the content is still JSON.

Data flow: The test starts a server, builds an initialize JSON-RPC request with request id 1, converts that request into JSON bytes, and sends those bytes as a binary WebSocket message. It waits for the matching response, checks that the response id is the same as the request id, converts the response payload into InitializeResponse, and verifies the session id is a valid UUID. Finally, it shuts the server down.

Call relations: Like the other WebSocket tests, this uses exec_server to create a real server under test. It constructs the request using the JSON-RPC protocol types, serializes it to bytes, sends it through the test WebSocket connection, and then relies on the server’s normal initialize path to produce a response.

Call graph: calls 1 internal fn (exec_server); 8 external calls (parse_str, Request, Integer, assert_eq!, panic!, from_value, to_value, to_vec).

async fn exec_server_rejects_browser_origin_websocket_handshake() -> anyhow::Result<()>

Purpose: This test verifies that the server refuses WebSocket connections that include a browser Origin header. This is a security check to reduce the risk that an untrusted web page can connect to the exec server.

Data flow: The test starts a server and builds a WebSocket connection request for that server’s URL. Before connecting, it adds an Origin header with the value https://evil.example, pretending the request came from a browser page. The connection attempt must fail; the test then checks that the failure is an HTTP response with status 403 Forbidden. It shuts the server down afterward.

Call relations: The test uses exec_server to launch the server, then bypasses the usual test connection helper so it can customize the WebSocket handshake request. It calls connect_async to attempt the handshake and expects the server’s WebSocket security layer to reject it before any normal JSON-RPC communication begins.

Call graph: calls 1 internal fn (exec_server); 4 external calls (from_static, bail!, assert_eq!, connect_async).

fn exec_params(process_id: &str) -> ExecParams

Purpose: Builds a standard request for starting a short-lived test process. Tests use it when they only care that some process runs briefly, not about the exact command.

Data flow: It takes a process ID string, asks sleep_argv for a small platform-appropriate sleep command, and passes both into exec_params_with_argv. The result is a complete ExecParams value ready to send to the handler.

Call relations: This is a convenience wrapper used by tests such as terminate_reports_false_after_process_exit and output_and_exit_are_retained_after_notification_receiver_closes. It delegates the detailed request-building work to exec_params_with_argv so the tests can stay focused on behavior.

Call graph: calls 2 internal fn (exec_params_with_argv, sleep_argv); called by 2 (output_and_exit_are_retained_after_notification_receiver_closes, terminate_reports_false_after_process_exit).

fn exec_params_with_argv(process_id: &str, argv: Vec<String>) -> ExecParams

Purpose: Builds a full process-start request from a process ID and an exact command line. Tests use it when they need a process to sleep, print output, or stay quiet for a while.

Data flow: It receives a process ID and a list of command arguments. It adds the current working directory, a small inherited environment containing PATH, and fixed test settings such as no terminal and no piped standard input, then returns an ExecParams request.

Call relations: This function is called by exec_params for the default sleep command and directly by tests that need custom command behavior. It relies on inherited_path_env so child commands can still find system programs.

Call graph: calls 3 internal fn (from, inherited_path_env, from_path); called by 3 (exec_params, long_poll_read_fails_after_session_resume, output_and_exit_are_retained_after_notification_receiver_closes); 1 external calls (current_dir).

fn inherited_path_env() -> HashMap<String, String>

Purpose: Creates the small environment map passed to test child processes. It preserves the PATH variable so shell commands like sleep, ping, or echo can be found.

Data flow: It starts with an empty map, checks whether the current test process has a PATH environment variable, and copies it into the map if present. It returns that map for use in process-start parameters.

Call relations: It is used by exec_params_with_argv while building an ExecParams request. This keeps environment setup in one small place instead of repeating it in every test helper.

Call graph: called by 1 (exec_params_with_argv); 2 external calls (new, var_os).

fn sleep_argv() -> Vec<String>

Purpose: Provides a short sleep command that works on the current operating system. It gives tests a simple process that stays alive briefly and then exits.

Data flow: It has no input. It chooses the Unix-style script sleep 0.1 or the Windows-style ping delay by passing both options to shell_argv, and returns the resulting command argument list.

Call relations: It is called by exec_params, which uses it as the default command for short process tests. The operating-system choice is handed off to shell_argv.

Call graph: calls 1 internal fn (shell_argv); called by 1 (exec_params).

fn shell_argv(unix_script: &str, windows_script: &str) -> Vec<String>

Purpose: Turns a small shell script into the correct command arguments for Unix or Windows. This lets the same tests run on different operating systems.

Data flow: It receives two script strings: one for Unix-like systems and one for Windows. It checks which operating system the test is running on, then returns an argument list using /bin/sh -c ... on Unix or the Windows command processor with /C ... on Windows.

Call relations: Helpers and tests call this when they need a portable command, including sleep_argv, long_poll_read_fails_after_session_resume, and output_and_exit_are_retained_after_notification_receiver_closes. It is the file’s small adapter between test intentions and operating-system-specific command syntax.

Call graph: called by 3 (long_poll_read_fails_after_session_resume, output_and_exit_are_retained_after_notification_receiver_closes, sleep_argv); 2 external calls (cfg!, vec!).

fn windows_command_processor() -> String

Purpose: Finds the Windows command shell to use for running test scripts. If Windows does not provide a COMSPEC value, it falls back to cmd.exe.

Data flow: It reads the COMSPEC environment variable. If that variable exists, it returns its value; otherwise it returns the string cmd.exe.

Call relations: This supports the Windows path for shell command construction. It keeps the fallback rule separate so the command-building code can stay simple.

Call graph: 1 external calls (var).

fn test_runtime_paths() -> ExecServerRuntimePaths

Purpose: Builds the runtime path information needed to create an ExecServerHandler in tests. This gives the handler the executable path it expects without requiring a full production setup.

Data flow: It reads the path of the currently running test executable and passes it into ExecServerRuntimePaths::new, with no Linux sandbox executable. It returns the runtime paths object or fails the test if those paths cannot be built.

Call relations: Several setup paths call this before creating a handler, including initialized_handler and tests that construct handlers directly. It supplies the same runtime-path setup everywhere so tests are consistent.

Call graph: calls 1 internal fn (new); called by 4 (active_session_resume_is_rejected, initialized_handler, long_poll_read_fails_after_session_resume, output_and_exit_are_retained_after_notification_receiver_closes); 1 external calls (current_exe).

async fn initialized_handler() -> Arc<ExecServerHandler>

Purpose: Creates an exec server handler that has already completed the initialization steps expected from a client connection. Tests use it when they want to start from a ready-to-use server state.

Data flow: It creates an outgoing notification channel, a session registry, and a handler with test runtime paths. It sends an initialize request, checks that the returned session ID is a valid UUID, marks the handler as initialized, and returns it wrapped in Arc, a shared pointer that lets async tasks hold the same handler safely.

Call relations: This setup helper is used by tests that do not need custom session-resume wiring, such as duplicate process ID and termination behavior tests. It calls test_runtime_paths as part of building the handler.

Call graph: calls 4 internal fn (new, new, test_runtime_paths, new); called by 2 (duplicate_process_ids_allow_only_one_successful_start, terminate_reports_false_after_process_exit); 3 external calls (new, parse_str, channel).

async fn duplicate_process_ids_allow_only_one_successful_start()

Purpose: Checks that two simultaneous requests cannot start two processes with the same process ID. This protects the server from confusing one client’s process with another copy that has the same name.

Data flow: It creates an initialized handler, clones the shared handler pointer twice, and launches two exec calls at the same time using the same process ID. It separates the results into successes and failures, expects exactly one of each, checks the duplicate-process error details, waits for the short process to finish, and shuts down the handler.

Call relations: This test relies on initialized_handler for setup and exec_params for the start requests. It exercises the handler’s concurrent process registration path by making both requests race each other.

Call graph: calls 1 internal fn (initialized_handler); 5 external calls (clone, from_millis, assert_eq!, join!, sleep).

async fn terminate_reports_false_after_process_exit()

Purpose: Checks that terminating a process that has already finished reports running: false. This matters because clients need a truthful answer, not a stale claim that the process is still alive.

Data flow: It starts a short test process, then repeatedly sends a terminate request for that process until the response says the process is no longer running. It gives the process up to one second to reach that state, then shuts down the handler.

Call relations: The test uses initialized_handler for a ready handler and exec_params for the short-lived process. It repeatedly calls the handler’s terminate operation to observe the transition from running or recently exited to definitely not running.

Call graph: calls 3 internal fn (from, exec_params, initialized_handler); 5 external calls (from_millis, from_secs, assert!, now, sleep).

async fn long_poll_read_fails_after_session_resume()

Purpose: Checks that a waiting read request fails clearly when its session is resumed by another connection. This prevents an old connection from quietly continuing to read after ownership has moved elsewhere.

Data flow: It creates a first handler and starts a quiet, long-running process. It then starts an async read request with a wait time, shuts down the first handler, creates a second handler using the same registry, and initializes it with the first session’s ID. Finally it waits for the old read task and checks that it failed with the expected “session resumed” error.

Call relations: This test builds handlers directly instead of using initialized_handler because it needs to share a SessionRegistry across two connections. It uses exec_params_with_argv and shell_argv to start a process that stays alive without producing output, making sure the read only finishes because the session was resumed.

Call graph: calls 7 internal fn (from, new, new, exec_params_with_argv, shell_argv, test_runtime_paths, new); 7 external calls (clone, new, from_millis, assert_eq!, channel, spawn, sleep).

async fn active_session_resume_is_rejected()

Purpose: Checks that a second connection cannot resume a session while the first connection is still attached. This protects one live client from being unexpectedly displaced by another.

Data flow: It creates a first handler, initializes a new session, then creates a second handler using the same session registry. The second handler tries to initialize with the first session’s ID, and the test checks that the request fails with the expected error message. It then shuts down the first handler.

Call relations: This test constructs its own handlers because it needs two connections sharing one registry. It uses test_runtime_paths during each handler setup and then exercises the initialization path that enforces exclusive session attachment.

Call graph: calls 4 internal fn (new, new, test_runtime_paths, new); 4 external calls (clone, new, assert_eq!, channel).

async fn output_and_exit_are_retained_after_notification_receiver_closes()

Purpose: Checks that process output and exit status are still saved even if the notification receiver has been dropped. This ensures clients can recover information by polling reads, even when live notifications cannot be delivered.

Data flow: It creates and initializes a handler with a notification channel, starts a process that prints two lines and exits, then drops the receiving end of the notification channel. It reads the process until closed, confirms the output and exit code were retained, waits briefly, starts a new process with the same ID to confirm the old finished process no longer blocks reuse, and shuts down.

Call relations: This test uses exec_params_with_argv and shell_argv for the printing command, then calls read_process_until_closed to collect saved output through the read API. It later uses exec_params to check that the process ID can be reused after retained exit data has been handled.

Call graph: calls 9 internal fn (from, new, new, exec_params, exec_params_with_argv, read_process_until_closed, shell_argv, test_runtime_paths, new); 5 external calls (new, from_millis, assert_eq!, channel, sleep).

async fn read_process_until_closed(
    handler: &ExecServerHandler,
    process_id: ProcessId,
) -> (String, Option<i32>)

Purpose: Reads all available output from a process until the server says the process record is closed. It is a test helper for turning repeated read responses into one final output string and exit code.

Data flow: It receives a handler reference and a process ID. It repeatedly sends exec_read requests, appends returned byte chunks to a string, tracks the latest sequence number so it does not reread the same chunks, records the exit code once the process has exited, and returns the collected output and exit code when the response says the process is closed.

Call relations: This helper is called by output_and_exit_are_retained_after_notification_receiver_closes. It drives the handler’s read API in a loop, using long-poll waits so the test can wait for output and closure without busy-spinning.

Call graph: calls 1 internal fn (exec_read); called by 1 (output_and_exit_are_retained_after_notification_receiver_closes); 6 external calls (from_secs, from_utf8_lossy, new, assert!, clone, now).

async fn exec_server_starts_process_over_websocket() -> anyhow::Result<()>

Purpose: This test proves that a client can start a process through the exec server's WebSocket API. It uses the harmless Unix command true, which starts and exits successfully, so the test focuses on the server protocol rather than on process output.

Data flow: The test starts a fresh test server, sends an initialize request with a client name, waits for the matching response, then sends an initialized notification to finish the handshake. It then sends a process/start request containing a chosen process id, command arguments, current working directory, environment, and input settings. The server replies with JSON, the test turns that JSON into an ExecResponse, and the final check confirms that the response contains the requested process id. The test then shuts the server down.

Call relations: This function calls the shared exec_server test helper to create a real server connection. It then drives the server using request and notification helpers on that test server object. The external JSON conversion helpers build and decode protocol messages, while assertions verify that the response from the server matches the expected start-process result.

Call graph: calls 1 internal fn (exec_server); 5 external calls (assert_eq!, panic!, from_value, json!, to_value).

async fn exec_server_defaults_omitted_pipe_stdin_to_closed_stdin() -> anyhow::Result<()>

Purpose: This test checks a subtle default: when pipeStdin is left out of a process/start request, the server should behave as if standard input is closed. That prevents clients from writing to a process unless they explicitly asked for a writable input pipe.

Data flow: The test starts and initializes the server, then starts a shell command without including pipeStdin in the request. The shell command would read from standard input if input were available. After confirming that the process started, the test sends a process/write request with a base64-encoded chunk of text. The server responds with a WriteResponse, and the test checks that the status is StdinClosed, meaning the write was rejected because there is no open input pipe. Finally, the test shuts the server down.

Call relations: Like the other tests, this function relies on exec_server to create the test server and uses the server fixture to send JSON-RPC messages. It hands process-start and process-write requests to the running server, then uses JSON decoding and equality assertions to confirm the server chose the safe default behavior for omitted standard-input settings.

Call graph: calls 1 internal fn (exec_server); 5 external calls (assert_eq!, panic!, from_value, json!, to_value).

async fn exec_server_resumes_detached_session_without_killing_processes() -> anyhow::Result<()>

Purpose: This test proves that reconnecting to an existing session does not kill processes that were already running. It checks that a session can be resumed by id and that a long-running process is still alive after the WebSocket connection is dropped and restored.

Data flow: The test starts a server and initializes a new session, saving the returned session id. It then starts a long-running shell command, sleep 5, under the process id proc-resume. Next it deliberately disconnects the WebSocket and reconnects. It sends another initialize request, this time including the saved session id, and checks that the server returns the same session information as before. After sending initialized again, it asks to read the process state. The response is decoded into a ReadResponse, and the test verifies there is no failure, the process has not exited, and the stream is not closed. It then sends process/terminate, checks that the server reports the process was running, and shuts everything down.

Call relations: This function uses the shared exec_server fixture to exercise the server as a real client would. It first establishes a session, then uses the fixture's disconnect and reconnect operations to simulate a dropped WebSocket. After resuming with the saved session id, it sends read and terminate requests to prove the server kept the process alive across the connection break.

Call graph: calls 1 internal fn (exec_server); 6 external calls (assert!, assert_eq!, panic!, from_value, json!, to_value).

async fn create_process_context(use_remote: bool) -> Result<ProcessContext>

Purpose: Builds the test setup for either local process execution or remote execution through a real exec-server. Tests use it so they can run the same checks against both backends.

Data flow: It receives a use_remote choice. If remote is requested, it starts an exec-server, builds a test environment that points at that server, and returns both the backend and the server harness. If local is requested, it builds a test environment with no server URL and returns only the backend.

Call relations: Most assertion helpers begin by calling this function. It hides the setup difference so tests such as the output, stdin, signal, and queued-event checks can focus on process behavior instead of connection setup.

Call graph: calls 2 internal fn (create_for_tests, exec_server); called by 12 (assert_exec_process_preserves_queued_events_before_subscribe, assert_exec_process_pushes_events, assert_exec_process_rejects_write_without_pipe_stdin, assert_exec_process_replays_events_after_close, assert_exec_process_retains_output_after_exit_until_streams_close, assert_exec_process_signal_interrupts_process, assert_exec_process_signal_reports_unsupported_on_windows, assert_exec_process_starts_and_exits, assert_exec_process_streams_output, assert_exec_process_write_then_read (+2 more)).

async fn assert_exec_process_starts_and_exits(use_remote: bool) -> Result<()>

Purpose: Checks the simplest promise of the process system: it can start a command and report that it exited successfully. It uses the true command, which immediately exits with code 0.

Data flow: It receives whether to test local or remote execution, creates the matching context, starts a process with ID proc-1, subscribes for wake notifications, reads until the process closes, and confirms the exit code is 0.

Call relations: The public test exec_process_starts_and_exits calls this helper. It relies on create_process_context for setup and collect_process_output_from_reads to wait through the process lifecycle.

Call graph: calls 4 internal fn (from, collect_process_output_from_reads, create_process_context, from_path); called by 1 (exec_process_starts_and_exits); 5 external calls (default, assert!, assert_eq!, current_dir, vec!).

async fn read_process_until_change(
    session: Arc<dyn ExecProcess>,
    wake_rx: &mut watch::Receiver<u64>,
    after_seq: Option<u64>,
) -> Result<ReadResponse>

Purpose: Reads from a process, and if nothing has changed yet, waits briefly for a wake-up signal before trying again. This prevents tests from guessing with sleeps while still avoiding hangs.

Data flow: It receives a process session, a wake receiver, and an optional sequence number saying where reading should continue. It first does a non-waiting read. If there is no output, no closure, and no failure, it waits up to two seconds for the process to announce a change, then reads again. It returns the latest read response.

Call relations: Output-collecting helpers use this as their polling loop. The signal test also uses it while waiting for a readiness message, and the disconnect test uses it to confirm a failed remote connection is visible through reads.

Call graph: called by 3 (assert_exec_process_signal_interrupts_process, collect_process_output_from_reads, remote_exec_process_reports_transport_disconnect); 3 external calls (from_secs, changed, timeout).

async fn collect_process_output_from_reads(
    session: Arc<dyn ExecProcess>,
    mut wake_rx: watch::Receiver<u64>,
) -> Result<(String, Option<i32>, bool)>

Purpose: Collects all output from a process by repeatedly using the process read API until the session closes. It is the main helper for tests that care about the final combined output and exit status.

Data flow: It receives a process session and its wake receiver. It keeps track of the last sequence number seen, appends every returned output chunk to a string, records the exit code when reported, and stops when the process is closed. It returns the collected output, optional exit code, and a true closed flag.

Call relations: Many assertion helpers call this after starting or interacting with a process. Internally it delegates the wait-and-read step to read_process_until_change, then hands the final result back to the specific test scenario.

Call graph: calls 1 internal fn (read_process_until_change); called by 9 (assert_exec_process_preserves_queued_events_before_subscribe, assert_exec_process_rejects_write_without_pipe_stdin, assert_exec_process_replays_events_after_close, assert_exec_process_retains_output_after_exit_until_streams_close, assert_exec_process_signal_interrupts_process, assert_exec_process_starts_and_exits, assert_exec_process_streams_output, assert_exec_process_write_then_read, assert_exec_process_write_then_read_without_tty); 4 external calls (clone, from_utf8_lossy, new, bail!).

async fn collect_process_output_from_events(
    session: Arc<dyn ExecProcess>,
) -> Result<(String, String, Option<i32>, bool)>

Purpose: Collects stdout, stderr, exit code, and closure by listening to pushed process events instead of polling with reads. This checks the event-subscription side of the API.

Data flow: It receives a process session, subscribes to its event stream, and waits for events with a timeout. Output events are split into stdout or stderr strings, exit events record the code, and a closed event ends the loop. If a failure event appears first, the function returns an error.

Call relations: The replay-after-close test calls this after the process has already finished through the read path. That verifies late event subscribers can still receive the completed process history.

Call graph: called by 1 (assert_exec_process_replays_events_after_close); 5 external calls (from_secs, from_utf8_lossy, new, bail!, timeout).

async fn collect_process_event_snapshots(
    session: Arc<dyn ExecProcess>,
) -> Result<Vec<ProcessEventSnapshot>>

Purpose: Records the exact sequence of process events in a compact test-friendly form. It is used when the order and sequence numbers matter, not just the final text.

Data flow: It receives a process session, subscribes to events, and converts each event into a ProcessEventSnapshot. Output bytes become readable text, exit and close events keep their sequence numbers, and the list is returned once a close event is seen.

Call relations: The event-order test calls this helper. It turns the live event stream into a plain list that can be compared against the expected stdout, stderr, exit, and close sequence.

Call graph: called by 1 (assert_exec_process_pushes_events); 6 external calls (from_secs, from_utf8_lossy, new, bail!, matches!, timeout).

async fn assert_exec_process_streams_output(use_remote: bool) -> Result<()>

Purpose: Checks that normal stdout from a running process can be read by clients. It runs a shell command that prints a known line after a short delay.

Data flow: It receives the local-or-remote choice, creates a context, starts a shell command, verifies the process ID, then reads until closure. It expects exactly session output\n, exit code 0, and a closed session.

Call relations: The public test exec_process_streams_output calls this helper. It uses create_process_context for backend setup and collect_process_output_from_reads to gather the process result.

Call graph: calls 3 internal fn (collect_process_output_from_reads, create_process_context, from_path); called by 1 (exec_process_streams_output); 5 external calls (default, assert!, assert_eq!, current_dir, vec!).

async fn assert_exec_process_pushes_events(use_remote: bool) -> Result<()>

Purpose: Checks that the process event stream reports stdout, stderr, exit, and close in the expected order. This is important for clients that subscribe to live events rather than repeatedly calling read.

Data flow: It receives the local-or-remote choice, starts a shell command that writes to stdout, then stderr, then exits with code 7. It collects event snapshots and compares them with the exact expected sequence.

Call relations: The public test exec_process_pushes_events calls this helper. It depends on collect_process_event_snapshots to turn asynchronous events into a comparable list.

Call graph: calls 3 internal fn (collect_process_event_snapshots, create_process_context, from_path); called by 1 (exec_process_pushes_events); 4 external calls (default, assert_eq!, current_dir, vec!).

async fn assert_exec_process_replays_events_after_close(use_remote: bool) -> Result<()>

Purpose: Checks that event subscribers can still see output after a process has already finished. This protects clients that attach late from missing the process history.

Data flow: It receives the local-or-remote choice, starts a command that prints two lines, and first drains it through the read API. After the process is closed, it subscribes to events and expects the same stdout, no stderr, exit code 0, and closure.

Call relations: The public test exec_process_replays_events_after_close calls this helper. It combines collect_process_output_from_reads and collect_process_output_from_events to compare the read history with the replayed event history.

Call graph: calls 4 internal fn (collect_process_output_from_events, collect_process_output_from_reads, create_process_context, from_path); called by 1 (exec_process_replays_events_after_close); 5 external calls (clone, default, assert_eq!, current_dir, vec!).

async fn assert_exec_process_retains_output_after_exit_until_streams_close(
    use_remote: bool,
) -> Result<()>

Purpose: Checks a subtle case where a parent process exits before a child process writes delayed output. The system must not mark the session fully closed until remaining output streams are drained.

Data flow: It receives the local-or-remote choice, starts a helper binary that exits its parent first and waits for a release file before writing late output. The function observes the exit code before closure, creates the release file, reads the late output, then drains the session and verifies the late text was preserved.

Call relations: The public test exec_process_retains_output_after_exit_until_streams_close calls this helper. It uses the shared test helper binary paths, temporary files, direct reads, and finally collect_process_output_from_reads to confirm the full lifecycle.

Call graph: calls 4 internal fn (current_test_binary_helper_paths, collect_process_output_from_reads, create_process_context, from_path); called by 1 (exec_process_retains_output_after_exit_until_streams_close); 11 external calls (default, from_secs, from_utf8_lossy, new, new, assert!, assert_eq!, current_dir, write, timeout (+1 more)).

async fn assert_exec_process_write_then_read(use_remote: bool) -> Result<()>

Purpose: Checks that writing to a process connected through a terminal-style interface works. The process reads one line from input and prints it back with a prefix.

Data flow: It receives the local-or-remote choice, starts a shell command with tty enabled, waits briefly for it to be ready, writes hello\n, and reads all output. It expects the echoed text to contain from-stdin:hello, exit code 0, and closure.

Call relations: The public test exec_process_write_then_read calls this helper. It uses create_process_context to start the backend and collect_process_output_from_reads to verify the written input became process output.

Call graph: calls 3 internal fn (collect_process_output_from_reads, create_process_context, from_path); called by 1 (exec_process_write_then_read); 7 external calls (default, from_millis, assert!, assert_eq!, current_dir, sleep, vec!).

async fn assert_exec_process_write_then_read_without_tty(use_remote: bool) -> Result<()>

Purpose: Checks that stdin writing also works without a terminal when an explicit stdin pipe is requested. A stdin pipe is a direct input channel to the child process.

Data flow: It receives the local-or-remote choice, starts a shell command with pipe_stdin enabled and tty disabled, writes hello\n, verifies the write was accepted, then reads the output and final status.

Call relations: The public test exec_process_write_then_read_without_tty calls this helper. It demonstrates the non-terminal input path and uses collect_process_output_from_reads for the final check.

Call graph: calls 3 internal fn (collect_process_output_from_reads, create_process_context, from_path); called by 1 (exec_process_write_then_read_without_tty); 6 external calls (default, from_millis, assert_eq!, current_dir, sleep, vec!).

async fn assert_exec_process_rejects_write_without_pipe_stdin(use_remote: bool) -> Result<()>

Purpose: Checks that the system refuses input when the process was not started with stdin open. This prevents callers from thinking bytes were delivered when there is nowhere to send them.

Data flow: It receives the local-or-remote choice, starts a shell command with no terminal and no stdin pipe, then tries to write ignored\n. It expects a StdinClosed status, then reads the process output and confirms the command saw end-of-file and exited normally.

Call relations: The public test exec_process_rejects_write_without_pipe_stdin calls this helper. It uses the normal read collector after the rejected write to prove the child process behaved as if stdin was closed.

Call graph: calls 3 internal fn (collect_process_output_from_reads, create_process_context, from_path); called by 1 (exec_process_rejects_write_without_pipe_stdin); 5 external calls (default, assert!, assert_eq!, current_dir, vec!).

async fn assert_exec_process_signal_interrupts_process(use_remote: bool) -> Result<()>

Purpose: Checks that sending an interrupt signal can stop a running Unix process and that the process can report its own signal handling output. An interrupt signal is like pressing Ctrl-C.

Data flow: It receives the local-or-remote choice, starts a shell loop that prints ready, installs an interrupt handler, and then spins forever. The function reads until it sees ready, sends an interrupt, drains the remaining output, and expects the signal-handler text plus exit code 7.

Call relations: The public test exec_process_signal_interrupts_process calls this helper. It uses read_process_until_change for the readiness phase and collect_process_output_from_reads after sending the signal.

Call graph: calls 4 internal fn (collect_process_output_from_reads, create_process_context, read_process_until_change, from_path); called by 1 (exec_process_signal_interrupts_process); 9 external calls (clone, default, from_utf8_lossy, new, bail!, assert!, assert_eq!, current_dir, vec!).

async fn assert_exec_process_signal_reports_unsupported_on_windows(use_remote: bool) -> Result<()>

Purpose: Checks the Windows-specific behavior for interrupting a non-terminal process. On that platform and backend, this kind of interrupt is expected to be unsupported and should produce a clear error.

Data flow: It receives the local-or-remote choice, starts a long-running Windows command, attempts to send an interrupt signal, and expects an error message explaining that process interrupt is not supported. It then terminates the process to clean up.

Call relations: The public Windows-only test exec_process_signal_reports_unsupported_on_windows calls this helper. It uses create_process_context for setup but checks the signal call directly instead of going through output collectors.

Call graph: calls 3 internal fn (from, create_process_context, from_path); called by 1 (exec_process_signal_reports_unsupported_on_windows); 5 external calls (default, bail!, assert!, current_dir, vec!).

async fn assert_exec_process_preserves_queued_events_before_subscribe(
    use_remote: bool,
) -> Result<()>

Purpose: Checks that output produced before a reader subscribes is not lost. This protects slow or late clients from missing early process output.

Data flow: It receives the local-or-remote choice, starts a shell command that immediately prints a line, deliberately waits, then subscribes to wake notifications and reads the process. It expects the earlier output, exit code 0, and closure.

Call relations: The public test exec_process_preserves_queued_events_before_subscribe calls this helper. It relies on collect_process_output_from_reads to prove that queued output is still available after the delay.

Call graph: calls 4 internal fn (from, collect_process_output_from_reads, create_process_context, from_path); called by 1 (exec_process_preserves_queued_events_before_subscribe); 7 external calls (default, from_millis, assert!, assert_eq!, current_dir, sleep, vec!).

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

Purpose: Checks that a remote process session reports a server connection loss clearly and consistently. Without this, callers might wait forever or receive confusing partial results after the exec-server disappears.

Data flow: It creates a remote-only context, starts a long-running process, subscribes to events, and also starts a pending read. Then it shuts down the server. It expects a failure event, a failed pending read, a failed later read that also marks the session closed, and a failed write after disconnect.

Call relations: This is a standalone test rather than a wrapper around an assertion helper. It still uses create_process_context for setup and read_process_until_change to check the post-disconnect read path.

Call graph: calls 4 internal fn (from, create_process_context, read_process_until_change, from_path); 9 external calls (clone, default, from_secs, bail!, assert!, current_dir, spawn, timeout, vec!).

async fn exec_process_starts_and_exits(use_remote: bool) -> Result<()>

Purpose: Runs the start-and-exit check as an actual async test for both local and remote modes. It is the test framework entry point for that scenario.

Data flow: The test framework supplies the use_remote case. The function passes that value into assert_exec_process_starts_and_exits and returns its success or failure.

Call relations: This wrapper connects the reusable assertion helper to the test runner. The helper does the real setup, process launch, and verification.

Call graph: calls 1 internal fn (assert_exec_process_starts_and_exits).

async fn exec_process_streams_output(use_remote: bool) -> Result<()>

Purpose: Runs the stdout streaming check as an actual async test for both local and remote modes. It confirms callers can read normal process output.

Data flow: The test framework supplies the local-or-remote parameter. The function forwards it to assert_exec_process_streams_output and returns the result.

Call relations: This wrapper exists so the same helper can be exercised by the test runner in two modes. The helper contains the process behavior check.

Call graph: calls 1 internal fn (assert_exec_process_streams_output).

async fn exec_process_pushes_events(use_remote: bool) -> Result<()>

Purpose: Runs the pushed-event ordering check as an actual async test for both local and remote modes. It focuses on the subscription API rather than polling reads.

Data flow: It receives use_remote from the parameterized test setup and calls assert_exec_process_pushes_events. The result from that helper becomes the test result.

Call relations: This is the test-runner-facing shell around the event assertion helper. The helper starts the command and compares the event sequence.

Call graph: calls 1 internal fn (assert_exec_process_pushes_events).

async fn exec_process_replays_events_after_close(use_remote: bool) -> Result<()>

Purpose: Runs the late-subscriber replay check as an actual async test for both local and remote modes. It verifies that finished process history remains available.

Data flow: It receives the local-or-remote test case value and passes it to assert_exec_process_replays_events_after_close. Any mismatch or error is returned to the test runner.

Call relations: This wrapper lets the reusable replay assertion run under the test framework. The assertion helper performs both read-based collection and event-based replay collection.

Call graph: calls 1 internal fn (assert_exec_process_replays_events_after_close).

async fn exec_process_retains_output_after_exit_until_streams_close(
    use_remote: bool,
) -> Result<()>

Purpose: Runs the late-output-after-exit check as an actual async test for both local and remote modes. It protects a tricky lifecycle edge case.

Data flow: It receives use_remote, calls assert_exec_process_retains_output_after_exit_until_streams_close, and returns that helper's result.

Call relations: This is the test entry point for the delayed-output scenario. The helper uses a test binary and temporary release file to create the edge case.

Call graph: calls 1 internal fn (assert_exec_process_retains_output_after_exit_until_streams_close).

async fn exec_process_write_then_read(use_remote: bool) -> Result<()>

Purpose: Runs the terminal-style stdin write check as an actual async test for both local and remote modes. It verifies that input sent to a process can affect its output.

Data flow: The parameterized test framework supplies use_remote. The function forwards it to assert_exec_process_write_then_read and returns the result.

Call relations: This wrapper links the stdin-through-tty scenario to the test runner. The assertion helper starts the process, writes input, and reads the response.

Call graph: calls 1 internal fn (assert_exec_process_write_then_read).

async fn exec_process_write_then_read_without_tty(use_remote: bool) -> Result<()>

Purpose: Runs the piped-stdin write check as an actual async test for both local and remote modes. It verifies input works even when no terminal is used.

Data flow: It receives the local-or-remote choice from the test framework, calls assert_exec_process_write_then_read_without_tty, and returns the outcome.

Call relations: This wrapper exposes the non-terminal stdin scenario to the test runner. The helper performs the actual write and read verification.

Call graph: calls 1 internal fn (assert_exec_process_write_then_read_without_tty).

async fn exec_process_rejects_write_without_pipe_stdin(use_remote: bool) -> Result<()>

Purpose: Runs the rejected-stdin-write check as an actual async test for both local and remote modes. It confirms callers get a clear status when stdin is closed.

Data flow: It receives use_remote, passes it to assert_exec_process_rejects_write_without_pipe_stdin, and returns success or failure.

Call relations: This wrapper connects the closed-stdin assertion helper to the test runner. The helper checks both the write status and the child process output.

Call graph: calls 1 internal fn (assert_exec_process_rejects_write_without_pipe_stdin).

async fn exec_process_signal_interrupts_process(use_remote: bool) -> Result<()>

Purpose: Runs the Unix interrupt-signal check as an actual async test for both local and remote modes. It verifies that a running process can be interrupted.

Data flow: It receives the local-or-remote value and calls assert_exec_process_signal_interrupts_process. The helper's result becomes the test result.

Call relations: This wrapper is enabled for Unix-like systems. The assertion helper waits for process readiness, sends the interrupt, and checks the resulting output and exit code.

Call graph: calls 1 internal fn (assert_exec_process_signal_interrupts_process).

async fn exec_process_signal_reports_unsupported_on_windows(use_remote: bool) -> Result<()>

Purpose: Runs the Windows unsupported-signal check as an actual async test for both local and remote modes. It verifies the backend gives a clear error instead of pretending the signal worked.

Data flow: It receives use_remote, calls assert_exec_process_signal_reports_unsupported_on_windows, and returns the result.

Call relations: This wrapper is enabled for Windows. The assertion helper starts the process, tries the unsupported interrupt, checks the message, and cleans up.

Call graph: calls 1 internal fn (assert_exec_process_signal_reports_unsupported_on_windows).

async fn exec_process_preserves_queued_events_before_subscribe(use_remote: bool) -> Result<()>

Purpose: Runs the queued-output preservation check as an actual async test for both local and remote modes. It verifies early output remains readable even if the client subscribes late.

Data flow: It receives the local-or-remote parameter and forwards it to assert_exec_process_preserves_queued_events_before_subscribe. The helper's result is returned to the test runner.

Call relations: This wrapper exposes the late-subscription scenario to the test runner. The assertion helper creates the delay, then proves the queued output is still available.

Call graph: calls 1 internal fn (assert_exec_process_preserves_queued_events_before_subscribe).

fn find_python() -> Option<String>

Purpose: Looks for a usable Python command on the current machine. Tests use this so they can skip Python-based checks cleanly instead of failing on systems without Python.

Data flow: It tries the command names python3 and python, asks each for its version, and checks whether the command succeeds. If one works, it returns that command name; if none work, it returns nothing.

Call relations: Several tests call this before launching Python. If it returns nothing, those tests print a skip message and stop early; if it returns a command name, they pass it into the process-spawning functions.

Call graph: called by 4 (pipe_drains_stderr_without_stdout_activity, pipe_process_round_trips_stdin, pty_preserving_inherited_fds_keeps_python_repl_running, pty_python_repl_emits_output_and_exits); 1 external calls (new).

fn setsid_available() -> bool

Purpose: Checks whether the Unix setsid tool is available. setsid starts a process in a new session, which is useful for testing detached child behavior.

Data flow: It first rules out Windows, where this tool is not expected. On other systems it runs setsid true; a successful exit means the feature is available, while errors or failed exits mean it is not.

Call relations: The detached-reader termination test calls this before doing Unix-style session work. If setsid is missing, the test skips itself rather than producing a misleading failure.

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

fn shell_command(program: &str) -> (String, Vec<String>)

Purpose: Wraps a short shell script in the right command for the operating system. This lets the same test idea run through cmd.exe on Windows or /bin/sh on Unix.

Data flow: It receives a script string. On Windows it returns the command interpreter plus /C arguments; on Unix it returns /bin/sh plus -c. The result is a program name and argument list ready to spawn.

Call relations: Many tests use this when they need a tiny shell program. It keeps those tests focused on process behavior instead of repeating platform-specific shell setup.

Call graph: called by 5 (pipe_and_pty_share_interface, pipe_process_can_expose_split_stdout_and_stderr, pipe_process_detaches_from_parent_session, pipe_terminate_aborts_detached_readers, pty_terminate_kills_background_children_in_same_process_group); 3 external calls (cfg!, var, vec!).

fn echo_sleep_command(marker: &str) -> String

Purpose: Builds a tiny command that prints a marker and waits briefly. Tests use this to confirm that spawned pipe and PTY processes both produce expected output before exiting.

Data flow: It receives marker text and formats a platform-specific shell snippet. The output is a command string that echoes the marker and then pauses for a short time.

Call relations: The shared-interface test passes this command through shell_command, then runs it once through a pipe process and once through a PTY process.

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

fn split_stdout_stderr_command() -> String

Purpose: Creates a command that writes one known line to standard output and another known line to standard error. This gives tests a simple way to verify that the two streams stay separate.

Data flow: It chooses Windows command syntax or Unix shell syntax. The returned script prints split-out to stdout and split-err to stderr.

Call relations: The split-stream pipe test wraps this script with shell_command, spawns it without stdin, and then compares the two collected streams to exact expected bytes.

Call graph: called by 1 (pipe_process_can_expose_split_stdout_and_stderr); 1 external calls (cfg!).

async fn collect_split_output(mut output_rx: tokio::sync::mpsc::Receiver<Vec<u8>>) -> Vec<u8>

Purpose: Reads every chunk from one output stream until that stream closes. It is used when a test wants the complete stdout or stderr stream by itself.

Data flow: It receives an async channel carrying byte chunks. It waits for chunks one by one, appends them to a growing byte buffer, and returns the full collected buffer when the sender is gone.

Call relations: Split-output tests run this in background tasks for stdout and stderr. Those tests then wait for the child to exit and compare the buffers this helper returns.

Call graph: calls 1 internal fn (recv); called by 3 (driver_backed_process_can_expose_split_stdout_and_stderr, driver_backed_process_drains_output_that_arrives_after_exit_signal, pipe_process_can_expose_split_stdout_and_stderr); 1 external calls (new).

fn combine_spawned_output(
    spawned: SpawnedProcess,
) -> (
    crate::ProcessHandle,
    tokio::sync::broadcast::Receiver<Vec<u8>>,
    tokio::sync::oneshot::Receiver<i32>,
)

Purpose: Turns a spawned process with separate stdout and stderr receivers into a simpler shape with one combined output receiver. This is useful for tests that only care whether text appeared somewhere.

Data flow: It receives a SpawnedProcess, takes out its session handle, stdout receiver, stderr receiver, and exit receiver, combines stdout and stderr into one broadcast stream, and returns the session, combined output, and exit signal.

Call relations: Most tests call this immediately after spawning a process. It hands them the session for writing or terminating, a unified output stream for assertions, and the exit receiver for completion checks.

Call graph: called by 11 (pipe_and_pty_share_interface, pipe_drains_stderr_without_stdout_activity, pipe_process_detaches_from_parent_session, pipe_process_round_trips_stdin, pipe_spawn_no_stdin_can_preserve_inherited_fds, pipe_terminate_aborts_detached_readers, pty_preserving_inherited_fds_keeps_python_repl_running, pty_python_repl_emits_output_and_exits, pty_spawn_can_preserve_inherited_fds, pty_spawn_with_inherited_fds_supports_resize (+1 more)); 1 external calls (combine_output_receivers).

async fn collect_output_until_exit(
    mut output_rx: tokio::sync::broadcast::Receiver<Vec<u8>>,
    exit_rx: tokio::sync::oneshot::Receiver<i32>,
    timeout_ms: u64,
) -> (Vec<u8>, i32)

Purpose: Collects process output while waiting for the process to finish. It also waits briefly after the exit signal so late-arriving terminal bytes are not accidentally missed.

Data flow: It receives a broadcast output stream, an exit-code receiver, and a timeout. It gathers bytes until either the process exits or the timeout expires; after exit, it drains any final output for a short quiet window. It returns the bytes collected and the exit code, or -1 on timeout or missing code.

Call relations: Many tests use this as their final collection step after sending input or starting a short-lived command. It bridges process execution and assertions by returning both visible output and completion status.

Call graph: called by 8 (pipe_and_pty_share_interface, pipe_drains_stderr_without_stdout_activity, pipe_process_round_trips_stdin, pipe_spawn_no_stdin_can_preserve_inherited_fds, pty_preserving_inherited_fds_keeps_python_repl_running, pty_python_repl_emits_output_and_exits, pty_spawn_can_preserve_inherited_fds, pty_spawn_with_inherited_fds_supports_resize); 5 external calls (new, pin!, select!, from_millis, now).

async fn wait_for_output_contains(
    output_rx: &mut tokio::sync::broadcast::Receiver<Vec<u8>>,
    needle: &str,
    timeout_ms: u64,
) -> anyhow::Result<Vec<u8>>

Purpose: Waits until PTY output contains a particular piece of text. This helps tests synchronize with an interactive process instead of guessing with sleeps.

Data flow: It reads output chunks until a deadline. Each chunk is added to a buffer, converted loosely to text, and checked for the requested substring. It returns the bytes seen so far on success or an error explaining what was collected on timeout or closure.

Call relations: The PTY resize-with-inherited-file-descriptors test uses this to wait for the child shell to report its initial terminal size before sending a resize.

Call graph: calls 1 internal fn (recv); called by 1 (pty_spawn_with_inherited_fds_supports_resize); 6 external calls (from_utf8_lossy, new, bail!, from_millis, now, timeout).

async fn wait_for_python_repl_ready(
    output_rx: &mut tokio::sync::broadcast::Receiver<Vec<u8>>,
    timeout_ms: u64,
    ready_marker: &str,
) -> anyhow::Result<Vec<u8>>

Purpose: Waits for a Python interactive session to print a known readiness marker. This avoids sending commands before Python is actually ready to receive them.

Data flow: It receives a PTY output stream, a timeout, and marker text. It keeps collecting bytes until the marker appears, then returns the collected bytes; if output closes or time runs out, it returns a detailed error.

Call relations: The basic PTY Python REPL test calls this after spawning Python. Once it succeeds, the test sends Python commands through the session writer.

Call graph: calls 1 internal fn (recv); called by 1 (pty_python_repl_emits_output_and_exits); 6 external calls (from_utf8_lossy, new, bail!, from_millis, now, timeout).

async fn wait_for_python_repl_ready_via_probe(
    writer: &tokio::sync::mpsc::Sender<Vec<u8>>,
    output_rx: &mut tokio::sync::broadcast::Receiver<Vec<u8>>,
    timeout_ms: u64,
    newline: &str,
)

Purpose: Checks that a Python REPL is ready by repeatedly sending a harmless print command and waiting to see its marker output. This is useful when startup banners or prompts are not reliable enough.

Data flow: It receives a writer, an output stream, a timeout, and the newline style. During the timeout it sends a probe command, watches output for a unique marker, and returns collected bytes when the marker appears. If the marker never appears, it reports what was seen.

Call relations: The Unix inherited-file-descriptor Python REPL test uses this before asking Python for its process id. It coordinates writing to the REPL with reading from the PTY.

Call graph: calls 1 internal fn (recv); called by 1 (pty_preserving_inherited_fds_keeps_python_repl_running); 10 external calls (send, from_utf8_lossy, new, bail!, cfg!, format!, min, from_millis, now, timeout).

fn process_exists(pid: i32) -> anyhow::Result<bool>

Purpose: Checks whether a Unix process id still refers to a live process. It is a small wrapper around the operating system’s process check.

Data flow: It receives a process id and calls kill(pid, 0), which asks the OS about the process without sending a real signal. It returns true if the process exists or permission is denied, false if the OS says there is no such process, and an error for unexpected failures.

Call relations: The process-exit waiting helper calls this repeatedly. Tests use that helper to confirm that termination actually kills background children.

Call graph: called by 1 (wait_for_process_exit); 2 external calls (last_os_error, kill).

async fn wait_for_marker_pid(
    output_rx: &mut tokio::sync::broadcast::Receiver<Vec<u8>>,
    marker: &str,
    timeout_ms: u64,
) -> anyhow::Result<i32>

Purpose: Reads process output until it finds a marker followed by a numeric process id. Tests use this when a child script prints the id of a process they later need to inspect.

Data flow: It receives an output stream, marker text, and a timeout. It collects output, searches for the marker, parses the digits after it as a process id, and returns that id. If the marker or full number never appears, it returns an error with the collected output.

Call relations: Tests for PTY termination and preserved-file-descriptor Python sessions call this after the child prints a tagged process id. The returned id is then passed to process-existence checks.

Call graph: calls 1 internal fn (recv); called by 2 (pty_preserving_inherited_fds_keeps_python_repl_running, pty_terminate_kills_background_children_in_same_process_group); 6 external calls (from_utf8_lossy, new, bail!, from_millis, now, timeout).

async fn wait_for_process_exit(pid: i32, timeout_ms: u64) -> anyhow::Result<bool>

Purpose: Polls a Unix process id until it disappears or a timeout is reached. This turns a process-kill expectation into a clear true-or-false result.

Data flow: It receives a process id and timeout. It repeatedly asks process_exists, sleeps briefly between checks, and returns true once the process is gone or false if the deadline passes.

Call relations: The PTY termination test uses this after calling terminate. If it reports that the child is still alive, the test cleans up with a stronger kill signal and then fails.

Call graph: calls 1 internal fn (process_exists); called by 1 (pty_terminate_kills_background_children_in_same_process_group); 3 external calls (from_millis, now, sleep).

async fn pty_python_repl_emits_output_and_exits() -> anyhow::Result<()>

Purpose: Tests that a Python interactive session can run through a PTY, accept input, produce output, and exit cleanly. This covers the core interactive-terminal use case.

Data flow: It finds Python, starts it in interactive quiet mode with a readiness print, combines its output, waits for readiness, sends a print command and exit(), then collects final output and exit code. The test passes only if the expected text appears and the exit code is zero.

Call relations: This test relies on the Python finder, the PTY spawner, the output combiner, the REPL readiness waiter, and the final output collector. Together they simulate a user typing into a terminal.

Call graph: calls 5 internal fn (default, collect_output_until_exit, combine_spawned_output, find_python, wait_for_python_repl_ready); 10 external calls (new, from_utf8_lossy, assert!, assert_eq!, cfg!, spawn_pty_process, eprintln!, format!, vars, vec!).

async fn pipe_process_round_trips_stdin() -> anyhow::Result<()>

Purpose: Tests that a pipe-backed process can receive text through stdin and echo it back. This verifies the ordinary non-terminal input path.

Data flow: It chooses a small echoing command, spawns it with pipes, sends roundtrip plus the platform newline, closes stdin, and gathers output and exit code. It expects the echoed word and a clean exit.

Call relations: The test uses find_python on Unix-like paths where Python is the echo program, then uses the shared combine-and-collect helpers to observe the spawned process.

Call graph: calls 3 internal fn (collect_output_until_exit, combine_spawned_output, find_python); 11 external calls (new, from_utf8_lossy, assert!, assert_eq!, cfg!, spawn_pipe_process, eprintln!, format!, var, vars (+1 more)).

async fn pipe_process_detaches_from_parent_session() -> anyhow::Result<()>

Purpose: Checks that a Unix pipe-spawned process starts in a separate session from the test runner. A separate session matters because process control and termination should not accidentally affect the parent.

Data flow: It records the parent session id, starts a shell that prints its own process id, reads that id from output, asks the OS for the child session id, and compares them. The child should be its own session leader and not share the parent session.

Call relations: This test uses shell_command to build the child script and combine_spawned_output to read the printed pid. It then waits for the child exit signal to confirm normal completion.

Call graph: calls 2 internal fn (combine_spawned_output, shell_command); 10 external calls (new, from_utf8_lossy, bail!, assert_eq!, assert_ne!, spawn_pipe_process, getsid, vars, from_millis, timeout).

async fn pipe_and_pty_share_interface() -> anyhow::Result<()>

Purpose: Confirms that pipe-spawned and PTY-spawned processes can be used through the same high-level interface. This matters because callers should not need two totally different workflows.

Data flow: It builds two short commands, one printing pipe_ok and one printing pty_ok, starts one through pipes and one through a PTY, then collects output and exit codes from both. Both must exit with zero and include their markers.

Call relations: This test ties together echo_sleep_command, shell_command, both spawn paths, the output combiner, and the exit collector to compare the two process styles side by side.

Call graph: calls 5 internal fn (default, collect_output_until_exit, combine_spawned_output, echo_sleep_command, shell_command); 7 external calls (new, assert!, assert_eq!, cfg!, spawn_pipe_process, spawn_pty_process, vars).

async fn pipe_drains_stderr_without_stdout_activity() -> anyhow::Result<()>

Purpose: Tests that a process writing heavily to standard error does not hang just because standard output is quiet. This guards against deadlocks caused by an unread stderr pipe filling up.

Data flow: It finds Python, runs a script that writes many large chunks to stderr, combines the output streams, and waits for exit. The test expects a zero exit code and some collected output.

Call relations: This test depends on find_python, pipe spawning, and collect_output_until_exit. It specifically stresses the reader side of the pipe implementation.

Call graph: calls 3 internal fn (collect_output_until_exit, combine_spawned_output, find_python); 7 external calls (new, assert!, assert_eq!, spawn_pipe_process, eprintln!, vars, vec!).

async fn pipe_process_can_expose_split_stdout_and_stderr() -> anyhow::Result<()>

Purpose: Verifies that pipe-spawned processes can expose stdout and stderr as separate streams. This is needed when callers must distinguish normal output from error output.

Data flow: It starts a no-stdin command that writes known bytes to both streams, launches separate collectors for stdout and stderr, waits for exit, and compares each stream to exact platform-specific expected bytes.

Call relations: This test uses split_stdout_stderr_command and shell_command to create predictable output, then uses collect_split_output tasks to drain the two receivers independently.

Call graph: calls 3 internal fn (collect_split_output, shell_command, split_stdout_stderr_command); 8 external calls (new, assert_eq!, cfg!, spawn_pipe_process_no_stdin, vars, spawn, from_millis, timeout).

async fn driver_backed_process_can_expose_split_stdout_and_stderr() -> anyhow::Result<()>

Purpose: Tests the generic driver-based process wrapper with separate stdout and stderr streams. This proves the wrapper preserves stream separation even when the process is supplied by a custom driver rather than the OS spawner.

Data flow: It creates manual channels for input, stdout, stderr, and exit. After wrapping them with spawn_from_driver, it sends one stdout chunk, one stderr chunk, closes the senders, sends exit code zero, and checks that the exposed receivers contain the right bytes.

Call relations: This test exercises spawn_from_driver directly and uses collect_split_output to observe what the wrapper exposes to callers.

Call graph: calls 1 internal fn (collect_split_output); 5 external calls (assert_eq!, spawn_from_driver, spawn, from_secs, timeout).

async fn driver_backed_process_can_resize_via_resizer_hook() -> anyhow::Result<()>

Purpose: Checks that a driver-backed session forwards terminal resize requests to its resizer callback. This matters for custom process backends that need to react when the terminal size changes.

Data flow: It builds a driver with a resizer function that sends the requested size through a one-shot channel. The test calls resize on the session, waits for the size to arrive, and compares it to the requested rows and columns.

Call relations: This test goes straight through spawn_from_driver. It confirms that the public session resize method reaches the driver hook.

Call graph: 7 external calls (new, assert_eq!, spawn_from_driver, new, new, from_secs, timeout).

async fn driver_backed_process_drains_output_that_arrives_after_exit_signal() -> anyhow::Result<()>

Purpose: Verifies that output arriving shortly after an exit signal is still delivered. This protects against losing the final tail of a process’s output.

Data flow: It creates a driver-backed process, sends exit code zero first, waits briefly, then sends a final stdout chunk and closes the sender. The test waits for the exposed exit and output, expecting to receive both the exit code and the late tail bytes.

Call relations: This test uses spawn_from_driver and collect_split_output to check an ordering edge case that can happen with real asynchronous readers.

Call graph: calls 1 internal fn (collect_split_output); 7 external calls (assert_eq!, spawn_from_driver, spawn, from_millis, from_secs, sleep, timeout).

async fn pipe_terminate_aborts_detached_readers() -> anyhow::Result<()>

Purpose: Tests that terminating a pipe-backed session stops reader tasks even when a detached subprocess keeps producing output. This prevents leaked background readers after the main session is terminated.

Data flow: It first checks for setsid. Then it starts a shell script that launches a detached loop printing tick, waits to see initial output, calls terminate, and watches for more output. The test passes only if no further chunks arrive or the stream closes.

Call relations: This test uses setsid_available, shell_command, pipe spawning, and the combined output receiver. It focuses on cleanup behavior after session termination.

Call graph: calls 3 internal fn (combine_spawned_output, setsid_available, shell_command); 7 external calls (new, bail!, spawn_pipe_process, eprintln!, vars, from_millis, timeout).

async fn pty_terminate_kills_background_children_in_same_process_group() -> anyhow::Result<()>

Purpose: Checks that terminating a PTY session kills a background child in the same process group. This is important for avoiding orphaned long-running commands after a terminal session is closed.

Data flow: It starts a shell in a PTY that launches sleep 1000 in the background, prints that child’s pid with a marker, and waits. The test reads the pid, confirms it exists, terminates the session, then waits for the child process to disappear.

Call relations: This test uses shell_command, PTY spawning, wait_for_marker_pid, process_exists, and wait_for_process_exit to prove that termination reaches the process group, not just the shell.

Call graph: calls 5 internal fn (default, combine_spawned_output, shell_command, wait_for_marker_pid, wait_for_process_exit); 6 external calls (new, assert!, spawn_pty_process, format!, kill, vars).

async fn pty_spawn_can_preserve_inherited_fds() -> anyhow::Result<()>

Purpose: Tests that a Unix PTY-spawned process can inherit a selected file descriptor. A file descriptor is a small OS number that points to an open file, pipe, or socket.

Data flow: It creates an OS pipe, passes the write end as a preserved descriptor to a shell running under a PTY, and has the shell write a marker into that descriptor. After the child exits, the test reads the pipe’s read end and checks for the marker.

Call relations: This test calls the Unix inherited-file-descriptor PTY spawner, then uses the usual output combiner and exit collector to confirm the child finished before checking the side pipe.

Call graph: calls 4 internal fn (default, spawn_process_with_inherited_fds, collect_output_until_exit, combine_spawned_output); 7 external calls (new, new, assert_eq!, last_os_error, pipe, vars, from_raw_fd).

async fn pty_preserving_inherited_fds_keeps_python_repl_running() -> anyhow::Result<()>

Purpose: Checks that preserving file descriptors does not accidentally break an interactive Python REPL running in a PTY. This guards against subtle spawn setup bugs.

Data flow: It finds Python, creates and preserves a pipe file descriptor, starts Python in a PTY, closes local copies, probes until the REPL responds, asks Python to print its pid, confirms that pid is still alive, then sends exit() and expects a clean exit.

Call relations: This test combines find_python, the inherited-fd PTY spawner, wait_for_python_repl_ready_via_probe, wait_for_marker_pid, and the final output collector. It tests inherited descriptors and interactivity together.

Call graph: calls 7 internal fn (default, spawn_process_with_inherited_fds, collect_output_until_exit, combine_spawned_output, find_python, wait_for_marker_pid, wait_for_python_repl_ready_via_probe); 9 external calls (new, assert!, assert_eq!, last_os_error, eprintln!, format!, pipe, vars, from_raw_fd).

async fn pty_spawn_with_inherited_fds_reports_exec_failures() -> anyhow::Result<()>

Purpose: Verifies that trying to spawn a missing executable through the inherited-file-descriptor PTY path returns a useful error. This is important so callers are not left with a fake session for a program that never started.

Data flow: It creates a pipe, asks the spawner to run a deliberately nonexistent command while preserving one descriptor, then drops the pipe ends. The test expects an error and checks that the message looks like a missing-file or command-not-found error.

Call relations: This test calls the inherited-fd PTY spawner directly. If spawning unexpectedly succeeds, it terminates the session and fails the test.

Call graph: calls 2 internal fn (default, spawn_process_with_inherited_fds); 7 external calls (new, bail!, assert!, last_os_error, pipe, vars, from_raw_fd).

async fn pty_spawn_with_inherited_fds_supports_resize() -> anyhow::Result<()>

Purpose: Tests that a PTY process spawned with inherited file descriptors still supports terminal resizing. This ensures the special file-descriptor setup does not disable normal PTY controls.

Data flow: It starts a shell under a PTY with an initial size, waits until the shell prints that starting size, resizes the session, sends input so the shell continues, and collects final output. The test expects the shell to report the new rows and columns and exit cleanly.

Call relations: This test uses wait_for_output_contains for synchronization, then calls the session resize method and collect_output_until_exit to verify the result.

Call graph: calls 4 internal fn (spawn_process_with_inherited_fds, collect_output_until_exit, combine_spawned_output, wait_for_output_contains); 8 external calls (new, from_utf8_lossy, assert!, assert_eq!, last_os_error, pipe, vars, from_raw_fd).

async fn pipe_spawn_no_stdin_can_preserve_inherited_fds() -> anyhow::Result<()>

Purpose: Tests that a Unix pipe-spawned process without stdin can still inherit selected file descriptors. This covers the no-stdin variant of the pipe spawner.

Data flow: It creates an OS pipe, tells the child shell about the write-end descriptor through an environment variable, spawns the shell with that descriptor preserved, and has it write a marker into the pipe. After the child exits, the test reads the marker from the read end.

Call relations: This test uses the Unix no-stdin inherited-fd pipe spawner, then combines and collects process output only to wait for a clean exit before checking the side-channel pipe data.

Call graph: calls 3 internal fn (spawn_process_no_stdin_with_inherited_fds, collect_output_until_exit, combine_spawned_output); 7 external calls (new, new, assert_eq!, last_os_error, pipe, vars, from_raw_fd).

fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result

Purpose: This gives each file-system implementation a simple display name: local or remote. It is useful when tests print which version they are running against.

Data flow: It receives a FileSystemImplementation value and a text formatter. It checks whether the value is Local or Remote, writes the matching word into the formatter, and returns whether that write succeeded.

Call relations: This is called automatically by Rust formatting code whenever a test or helper prints a FileSystemImplementation. It does not start any file system itself; it only supplies the human-readable label used around the larger test flow.

Call graph: 1 external calls (write_str).

async fn create_file_system_context(
    implementation: FileSystemImplementation,
) -> Result<FileSystemContext>

Purpose: This prepares the file-system object that tests will exercise. Depending on the requested implementation, it either builds a local file-system instance or starts/connects to a remote exec server and uses its file-system interface.

Data flow: It takes a choice: Local or Remote. For Local, it finds the helper program paths needed by the runtime, builds runtime path settings from them, and creates a local file-system object. For Remote, it starts a test exec server, creates a test environment pointing at that server’s WebSocket address, and gets the file-system interface from that environment. It returns a FileSystemContext containing the ready-to-use file system and the extra objects needed to keep that setup alive.

Call relations: Many file-system tests call this at the start so the same test can run against local and remote implementations. It delegates local setup to helper-path and runtime-path constructors, and remote setup to the test exec-server launcher and test environment builder.

Call graph: calls 5 internal fn (create_for_tests, with_runtime_paths, new, exec_server, test_codex_helper_paths); called by 34 (assert_canonicalize_resolves_directory_alias, assert_sandboxed_canonicalize_resolves_directory_alias, file_system_copy_copies_directory_recursively, file_system_copy_copies_file, file_system_copy_rejects_copying_directory_into_descendant, file_system_copy_rejects_directory_without_recursive, file_system_create_directory_creates_nested_directories, file_system_get_metadata_reports_files_and_directories, file_system_read_directory_lists_entries, file_system_read_file_returns_bytes (+15 more)); 1 external calls (new).

fn absolute_path(path: std::path::PathBuf) -> AbsolutePathBuf

Purpose: This converts a normal path into the project’s AbsolutePathBuf, but only after proving the path is absolute. An absolute path starts from the root of the file system, rather than being relative to the current folder.

Data flow: It receives a standard path value. It first checks that the path is absolute and stops the test immediately if it is not. Then it converts the path into AbsolutePathBuf and returns it. If conversion fails despite the earlier check, the test fails with a clear message.

Call relations: Sandbox helpers call this before creating permission rules, because sandbox entries need trustworthy absolute paths. Tests can also call it directly when they need to compare or build permission profiles using the project’s absolute-path type.

Call graph: calls 1 internal fn (try_from); called by 3 (sandbox_context_from_profile_preserves_workspace_write_read_only_subpaths, read_only_sandbox, workspace_write_sandbox); 1 external calls (assert!).

fn read_only_sandbox(readable_root: std::path::PathBuf) -> FileSystemSandboxContext

Purpose: This builds a sandbox context that allows reading from one given root folder but does not grant write access there. Tests use it to check that read operations work while unsafe writes are blocked.

Data flow: It receives a path for the readable root. It converts that path into the project’s absolute-path type, wraps it in a sandbox entry marked with read access, and passes that entry into the shared sandbox builder. It returns a complete FileSystemSandboxContext ready to use in a test.

Call relations: Tests call this when they need a controlled read-only environment, such as checking metadata, reading files, or making sure symbolic-link escape attempts are rejected. It relies on absolute_path for path validation and sandbox_context to turn the rule into the final permission context.

Call graph: calls 2 internal fn (absolute_path, sandbox_context); called by 7 (assert_sandboxed_canonicalize_resolves_directory_alias, file_system_sandboxed_metadata_and_read_allow_readable_root, file_system_sandboxed_write_allows_additional_write_root, file_system_read_directory_rejects_symlink_escape, file_system_sandboxed_read_rejects_symlink_escape, file_system_sandboxed_read_rejects_symlink_parent_dotdot_escape, file_system_sandboxed_write_rejects_unwritable_path); 1 external calls (vec!).

fn workspace_write_sandbox(
    writable_root: std::path::PathBuf,
) -> FileSystemSandboxContext

Purpose: This builds a sandbox context that allows writing inside one given workspace root. Tests use it to check that valid writes are accepted and writes outside the allowed area are rejected.

Data flow: It receives a path for the writable root. It verifies and converts that path to an absolute-path value, creates a sandbox entry marked with write access, and sends that entry to the shared sandbox builder. It returns the finished sandbox context.

Call relations: Tests call this before file operations that should be allowed to create, copy, or remove items in a workspace. Like read_only_sandbox, it uses absolute_path for safe path conversion and sandbox_context to produce the common permission structure.

Call graph: calls 2 internal fn (absolute_path, sandbox_context); called by 11 (sandbox_context_from_profile_preserves_workspace_write_read_only_subpaths, file_system_copy_preserves_symlink_source, file_system_copy_rejects_symlink_escape_destination, file_system_copy_rejects_symlink_escape_source, file_system_create_directory_rejects_symlink_escape, file_system_remove_rejects_symlink_escape, file_system_remove_removes_symlink_not_target, file_system_sandboxed_write_allows_explicit_alias_roots, file_system_sandboxed_write_preserves_existing_hard_link, file_system_sandboxed_write_rejects_symlink_escape (+1 more)); 1 external calls (vec!).

fn sandbox_context(entries: Vec<FileSystemSandboxEntry>) -> FileSystemSandboxContext

Purpose: This is the common builder that turns a list of file-system permission entries into a full sandbox context. It also locks down network access, so these file-system tests stay focused on file permissions.

Data flow: It receives a list of sandbox entries, where each entry names a path and the kind of access allowed there. It creates a restricted file-system sandbox policy from those entries, combines it with a restricted network policy inside a permission profile, and converts that profile into a FileSystemSandboxContext. The returned context is what file-system operations use to decide what is allowed.

Call relations: read_only_sandbox and workspace_write_sandbox both hand their single permission rule to this function. This keeps the policy-building details in one place, so the individual helpers only need to say what kind of file access they want.

Call graph: calls 3 internal fn (from_permission_profile, from_runtime_permissions, restricted); called by 2 (read_only_sandbox, workspace_write_sandbox).

fn sandbox_context_from_profile_preserves_workspace_write_read_only_subpaths() -> Result<()>

Purpose: This test makes sure that when a workspace-write sandbox is converted into a permission profile and back into policy form, its read-only subpaths are not lost. In particular, it checks that a .git directory inside a writable workspace remains protected as read-only.

Data flow: It starts with a temporary writable folder containing a .git folder. It builds a workspace-write sandbox from that folder, converts the sandbox permissions into a permission profile, asks the resulting file-system policy for writable roots, and then checks that the writable root still lists the canonical .git path as read-only. The output is no returned value; the test passes if the assertion holds and fails otherwise.

Call relations: The Rust test runner calls this as a standalone unit test. Inside the test, workspace_write_sandbox creates the sandbox rules, absolute_path normalizes paths for comparison, and standard file-system calls create and canonicalize the temporary directories before the assertion checks the preserved policy.

Call graph: calls 2 internal fn (absolute_path, workspace_write_sandbox); 5 external calls (new, assert!, panic!, canonicalize, create_dir_all).

async fn file_system_get_metadata_reports_files_and_directories(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test checks that the file-system API reports basic facts correctly for both files and directories. It verifies fields such as whether a path is a file or folder, its size, and that modification times are present.

Data flow: It receives a file-system implementation choice, local or remote. It creates a test context, writes one file, creates one directory, asks the API for metadata for each path, and compares the returned FileMetadata to the expected values. The test changes only temporary disk contents and succeeds when both metadata responses match reality.

Call relations: The parameterized test runner calls this once for each implementation. The test uses create_file_system_context to obtain the implementation under test, converts disk paths with PathUri::from_path, then calls the API’s get_metadata operation and checks the answer with assertions.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 5 external calls (new, assert!, assert_eq!, create_dir, write).

async fn file_system_create_directory_creates_nested_directories(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test confirms that the API can create nested directories when recursive creation is requested. Without this behavior, callers would have to create each parent folder one by one.

Data flow: It takes the implementation choice, builds a file-system context, chooses a nested path inside a temporary folder, and calls create_directory with recursive: true. After the call, it checks the actual disk to confirm that the nested directory exists.

Call relations: The test runner invokes this for local and remote modes. It relies on create_file_system_context for the file-system object and PathUri::from_path to pass the target path into the API in the format the exec server expects.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 2 external calls (new, assert!).

async fn file_system_write_file_writes_bytes(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test checks that writing raw bytes through the file-system API creates a file with exactly those bytes. It protects against implementations that accidentally change, truncate, or fail to write the content.

Data flow: It creates a temporary file path, sends the byte sequence hello from trait into write_file, and then reads the file back directly from disk. The before state is an absent file; the after state is a file containing exactly the requested bytes.

Call relations: The parameterized test runner runs this in both implementation modes. The test obtains the file-system API through create_file_system_context, converts the path with PathUri::from_path, calls write_file, and uses a direct disk read as the independent check.

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

fn path_uri_join_and_parent_preserve_lexical_paths() -> Result<()>

Purpose: This test checks the behavior of PathUri path joining and parent lookup. It is especially concerned that paths are treated lexically, meaning the text of the path is preserved rather than automatically simplified or resolved on disk.

Data flow: It creates a base PathUri, joins a nested file path onto it, asks for the parent path, and compares both results to expected PathUri values. It also joins ../outside and confirms that the parent-traversal text is kept as part of the path rather than being resolved away.

Call relations: The Rust test runner calls this directly. The test focuses on PathUri::from_path, join, and parent, using assertions to lock down path-string behavior that other file-system tests and API calls depend on.

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

async fn file_system_read_file_returns_bytes(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test confirms that reading a file through the API returns the exact bytes stored on disk. It checks the binary-safe read path, not just text reading.

Data flow: It creates a temporary file containing hello from trait, converts its path to a PathUri, and calls read_file. The returned byte vector is compared with the original bytes written to disk.

Call relations: The parameterized test runner runs this for both local and remote implementations. The test sets up the context with create_file_system_context, prepares the fixture with a normal disk write, then asks the file-system API to read it back.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 3 external calls (new, assert_eq!, write).

async fn file_system_read_file_stream_returns_bounded_chunks(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test makes sure streamed file reading returns all data while keeping each piece within the configured maximum chunk size. Streaming matters for large files because it avoids needing to move the whole file as one giant block.

Data flow: It builds a temporary binary file a little larger than two chunks, reads it through read_file_stream, collects all stream pieces, and checks two things: every piece is non-empty and no larger than FILE_READ_CHUNK_SIZE, and all pieces joined together equal the original file contents.

Call relations: The test runner calls this once per implementation. The test gets the file-system object from create_file_system_context, uses PathUri::from_path for the file address, and then consumes the returned asynchronous stream with try_collect before making assertions.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 4 external calls (new, assert!, assert_eq!, write).

async fn file_system_read_file_text_returns_string(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test checks the API path for reading a file as text. It verifies that valid text bytes are returned as the expected string.

Data flow: It writes a temporary text file, calls read_file_text with that file’s PathUri, and compares the returned string to hello from trait. The file remains on disk until the temporary directory is cleaned up.

Call relations: The parameterized test runner invokes this for both local and remote implementations. The test creates the context, prepares the file with a standard write, then uses the API’s text-specific read operation rather than the raw byte reader.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 3 external calls (new, assert_eq!, write).

async fn file_system_copy_copies_file(implementation: FileSystemImplementation) -> Result<()>

Purpose: This test confirms that the API can copy a regular file from one path to another. It ensures the destination file contains the same text as the source.

Data flow: It writes a source file in a temporary folder, calls copy with recursive: false, and then reads the destination file directly from disk. The result should be a new file whose contents match the source.

Call relations: The parameterized test runner runs this in both implementation modes. The test obtains the API from create_file_system_context, converts source and destination paths with PathUri::from_path, calls copy, and verifies the result independently through the standard file system.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 3 external calls (new, assert_eq!, write).

async fn file_system_copy_copies_directory_recursively(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test checks that directory copying works when recursive copying is explicitly requested. It proves that nested folders and files are carried over, not just the top-level directory name.

Data flow: It creates a source directory with a nested folder and file, calls copy with recursive: true, and then reads the expected nested file under the copied directory. The successful after state is a copied directory tree containing the same nested text file.

Call relations: The parameterized test runner calls this for local and remote implementations. The test uses create_file_system_context and PathUri::from_path to reach the API, while ordinary disk operations create the source tree and verify the copied tree.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 4 external calls (new, assert_eq!, create_dir_all, write).

async fn file_system_read_directory_lists_entries(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test verifies that reading a directory returns its immediate children with correct names and file-versus-folder flags. It makes sure callers can discover what is inside a folder without opening each entry first.

Data flow: It creates a temporary directory containing one nested directory and one text file. It calls read_directory, sorts the returned entries by name so ordering does not matter, and compares them to the expected ReadDirectoryEntry values.

Call relations: The parameterized test runner invokes this for both implementations. The test prepares the directory on disk, asks the file-system API to list it, and then uses assertions to confirm that the API’s summary matches the created structure.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 4 external calls (new, assert_eq!, create_dir_all, write).

async fn file_system_remove_removes_directory(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test checks that the API can delete a directory tree when recursive and force options are enabled. It ensures cleanup operations can remove non-empty folders.

Data flow: It creates a temporary directory with a nested child directory, calls remove with recursive: true and force: true, and then checks that the original directory path no longer exists. The visible effect is deletion of the temporary directory tree.

Call relations: The test runner runs this for local and remote modes. The test uses create_file_system_context to get the implementation, turns the target into a PathUri, and then calls the API’s remove operation before checking the disk.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 3 external calls (new, assert!, create_dir_all).

async fn file_system_write_file_reports_missing_parent(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test confirms that writing a file fails clearly when its parent directory does not exist. It protects callers from silent directory creation or misleading success reports.

Data flow: It chooses a path inside a missing folder and calls write_file. If the write unexpectedly succeeds, the test fails immediately; otherwise it checks that the error kind is NotFound and that no file appeared at the requested path.

Call relations: The parameterized test runner calls this for both implementations. The test goes through create_file_system_context and PathUri::from_path, then focuses on the error returned by write_file rather than a successful result.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 4 external calls (new, bail!, assert!, assert_eq!).

async fn file_system_copy_rejects_directory_without_recursive(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test makes sure copying a directory without the recursive option is rejected with a specific error. That prevents surprising partial copies or ambiguous behavior.

Data flow: It creates an empty source directory, calls copy with recursive: false, expects an error, and then checks both the error kind and the human-readable message. No destination directory should be successfully copied.

Call relations: The parameterized test runner runs this for local and remote implementations. The test sets up the source directory, sends source and destination PathUri values into the API, and validates that the copy operation refuses the request in the documented way.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 3 external calls (new, assert_eq!, create_dir_all).

async fn file_system_sandboxed_metadata_and_read_allow_readable_root(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test verifies that a read-only sandbox still allows safe read operations inside its allowed root. It checks both metadata lookup and file reading under those permission rules.

Data flow: It creates an allowed directory with a file, builds a read-only sandbox for that directory, then calls get_metadata and read_file with the sandbox attached. The returned metadata and bytes must match the file on disk.

Call relations: The parameterized test runner invokes this in both implementation modes. The test uses read_only_sandbox to build the permission boundary, then passes that sandbox into file-system API calls to prove that allowed reads are not blocked.

Call graph: calls 3 internal fn (create_file_system_context, read_only_sandbox, from_path); 4 external calls (new, assert_eq!, create_dir_all, write).

async fn assert_canonicalize_resolves_directory_alias(
    implementation: FileSystemImplementation,
    create_directory_alias: impl FnOnce(&Path, &Path) -> Result<()>,
) -> Result<()>

Purpose: This shared helper checks that canonicalization resolves a directory alias to the real underlying path. An alias may be a symlink or a platform-specific directory junction, and callers need the true path for reliable permission and identity checks.

Data flow: It receives an implementation choice and a callback that creates an alias from one directory path to another. It creates a real source directory with a nested file, asks the callback to create the alias, builds the alias-based requested path and the real expected path, verifies they differ before canonicalization, then calls canonicalize and checks that the result equals the real path.

Call relations: This helper is called by alias-specific tests such as file_system_canonicalize_resolves_directory_symlink and file_system_canonicalize_resolves_directory_junction. Those callers provide the alias-creation behavior, while this helper supplies the common setup and assertion flow against the file-system API.

Call graph: calls 2 internal fn (create_file_system_context, from_path); called by 2 (file_system_canonicalize_resolves_directory_symlink, file_system_canonicalize_resolves_directory_junction); 6 external calls (new, assert_eq!, assert_ne!, canonicalize, create_dir_all, write).

async fn assert_sandboxed_canonicalize_resolves_directory_alias(
    implementation: FileSystemImplementation,
    create_directory_alias: impl FnOnce(&Path, &Path) -> Result<()>,
) -> Result<()>

Purpose: This shared helper checks that canonicalization still resolves aliases correctly when a sandbox is active. It proves that read permission over the surrounding temporary area is enough to resolve an allowed alias path to its real target.

Data flow: It receives an implementation choice and an alias-creation callback. It creates a source directory and nested file, creates an alias to the source, builds a read-only sandbox covering the temporary root, compares the alias path with the real canonical path to ensure they are different, then calls canonicalize with the sandbox and expects the real path back.

Call relations: This helper is used by sandboxed alias tests such as file_system_sandboxed_canonicalize_resolves_directory_symlink and file_system_sandboxed_canonicalize_resolves_directory_junction. The callers decide what kind of alias to create; this helper checks the common sandboxed behavior.

Call graph: calls 3 internal fn (create_file_system_context, read_only_sandbox, from_path); called by 2 (file_system_sandboxed_canonicalize_resolves_directory_symlink, file_system_sandboxed_canonicalize_resolves_directory_junction); 6 external calls (new, assert_eq!, assert_ne!, canonicalize, create_dir_all, write).

async fn file_system_sandboxed_write_allows_additional_write_root(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test verifies that extra permissions can extend a read-only sandbox with a new writable root. It matters because some operations may need temporary or user-approved write access outside the original read-only area.

Data flow: It creates separate readable and writable temporary directories. It starts with a read-only sandbox for the readable directory, builds an additional permission profile that marks the writable directory as writable, combines the original and additional policies, updates the sandbox, and then writes a file into the added writable root. Finally it reads the file from disk to confirm it was created with the expected bytes.

Call relations: The parameterized test runner calls this for local and remote implementations. The test uses read_only_sandbox for the starting permissions, effective_file_system_sandbox_policy and effective_network_sandbox_policy to merge in the extra permissions, then calls write_file through the file-system API to prove the merged sandbox is honored.

Call graph: calls 7 internal fn (create_file_system_context, read_only_sandbox, from_read_write_roots, from_runtime_permissions_with_enforcement, effective_file_system_sandbox_policy, effective_network_sandbox_policy, from_path); 4 external calls (new, assert_eq!, create_dir_all, vec!).

async fn file_system_copy_rejects_copying_directory_into_descendant(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: This test ensures the API refuses to copy a directory into one of its own children. Without this guard, a recursive copy could chase itself forever or create an endlessly nested directory tree.

Data flow: It creates a source directory with a nested child directory, then tries to copy the source into a path inside that child while using recursive: true. The expected output is an InvalidInput error with a specific message explaining that a directory cannot be copied to itself or one of its descendants.

Call relations: The parameterized test runner runs this for both implementations. The test sets up the risky directory shape on disk, sends the copy request through the file-system API, and validates that the API stops the operation before any runaway recursive copy can happen.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 3 external calls (new, assert_eq!, create_dir_all).

fn assert_sandbox_denied(error: &std::io::Error)

Purpose: Checks that an error looks like a proper sandbox denial. Different Unix systems report blocked access with slightly different error kinds and messages, so this helper accepts the expected safe variations.

Data flow: It receives an input/output error from a failed file operation. It inspects the error kind and message, then either accepts it as a valid sandbox rejection or fails the test if the error looks unrelated.

Call relations: The symlink-escape and unwritable-path tests call this after an operation is expected to fail. It gives those tests one shared rule for deciding whether the failure really came from sandbox protection.

Call graph: called by 8 (file_system_copy_rejects_symlink_escape_destination, file_system_copy_rejects_symlink_escape_source, file_system_create_directory_rejects_symlink_escape, file_system_read_directory_rejects_symlink_escape, file_system_remove_rejects_symlink_escape, file_system_sandboxed_read_rejects_symlink_escape, file_system_sandboxed_write_rejects_symlink_escape, file_system_sandboxed_write_rejects_unwritable_path); 4 external calls (assert!, kind, to_string, panic!).

fn assert_normalized_path_rejected(error: &std::io::Error)

Purpose: Checks that a path rejected after .. cleanup failed in an acceptable way. This is used for a tricky case where path normalization can turn a symlink escape attempt into either a missing-file error or a sandbox denial.

Data flow: It takes an error from a failed read. It looks at the kind and text of that error, then accepts only the known safe outcomes: not found, permission denied, or invalid input with a sandbox-like message.

Call relations: The parent-dot-dot symlink test calls this because that scenario can fail at slightly different layers. This helper keeps the test focused on the important point: the outside file was not read.

Call graph: called by 1 (file_system_sandboxed_read_rejects_symlink_parent_dotdot_escape); 4 external calls (assert!, kind, to_string, panic!).

fn alias_root_candidate() -> Result<Option<PathBuf>>

Purpose: Finds a temporary directory path that is an alias for another real path, if the current system has one. This lets a test check that explicitly allowed alias roots still work.

Data flow: It looks at /tmp and the system temporary directory. For each candidate, it checks whether it exists and whether its canonical, fully resolved path differs from the written path; if so, it returns that candidate.

Call relations: The alias-root write test calls this first. If no suitable alias exists on the machine, the test exits successfully because there is nothing meaningful to check.

Call graph: called by 1 (file_system_sandboxed_write_allows_explicit_alias_roots); 2 external calls (new, temp_dir).

fn create_directory_symlink(target: &Path, alias: &Path) -> Result<()>

Purpose: Creates a Unix symbolic link from one directory path to another. The shared canonicalization tests use it to build a directory alias.

Data flow: It receives a target path and an alias path. It asks the operating system to create a symlink at the alias that points to the target, then returns success or the operating system error.

Call relations: This function is passed into shared tests as the Unix-specific way to create a directory alias. Those shared tests then verify that canonicalization resolves the alias correctly.

Call graph: 1 external calls (symlink).

fn write_fake_bwrap(bin_dir: &Path) -> Result<PathBuf>

Purpose: Creates a fake bwrap executable for a Linux test. bwrap is bubblewrap, a sandboxing command; the fake version records how it was invoked and then runs the inner command.

Data flow: It receives a directory where the fake executable should live. It creates the directory, writes a shell script named bwrap, marks it executable, and returns the path to that fake program.

Call relations: The Linux sandbox-helper test calls this to prove the file system helper searches the preserved PATH. The fake executable writes a log so the test can confirm it was actually used.

Call graph: called by 1 (sandboxed_file_system_helper_finds_bwrap_on_preserved_path); 5 external calls (join, create_dir_all, metadata, set_permissions, write).

async fn file_system_canonicalize_resolves_directory_symlink(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that canonicalizing a directory symlink returns the real directory path. Canonicalizing means asking the system for the true path after following links.

Data flow: It receives a chosen file system implementation from the test framework. It passes that implementation and the Unix symlink-creation helper to shared test code, which builds the scenario and checks the result.

Call relations: This is a thin Unix wrapper around shared file system tests. It runs once for the local implementation and once for the remote implementation.

Call graph: calls 1 internal fn (assert_canonicalize_resolves_directory_alias).

async fn file_system_sandboxed_canonicalize_resolves_directory_symlink(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that canonicalization still resolves directory symlinks correctly when a sandbox is involved. This matters because sandbox checks must not break normal path resolution inside allowed areas.

Data flow: It receives the local or remote implementation choice. It hands that choice and the symlink-creation helper to shared sandbox-aware canonicalization test code.

Call relations: Like the non-sandbox version, this delegates the main work to shared tests. It supplies the Unix-specific link creation step and runs for both supported file system implementations.

Call graph: calls 1 internal fn (assert_sandboxed_canonicalize_resolves_directory_alias).

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

Purpose: On Linux, verifies that sandboxed file operations can find bwrap through the PATH environment variable passed to the exec server. This guards against breaking sandbox startup when bwrap is not in a hard-coded location.

Data flow: It creates a temporary fake bwrap, prepends its directory to PATH, starts an exec server with that environment, then writes a file through a sandboxed file system call. Afterward it reads the created file and the fake bwrap log to confirm the sandbox helper used the fake command with the expected arguments.

Call relations: This test calls the fake-bwrap setup helper, starts an exec server with a custom environment, creates a test environment from that server, and then uses the file system API. It ties environment setup, sandbox invocation, and a real write operation together.

Call graph: calls 5 internal fn (create_for_tests, exec_server_with_env, workspace_write_sandbox, write_fake_bwrap, from_path); 9 external calls (new, assert!, assert_eq!, join_paths, split_paths, var_os, create_dir_all, read_to_string, vec!).

async fn file_system_get_metadata_reports_symlink_targets(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that metadata for a symlink reports both that the path is a symlink and what kind of target it points to. For example, a link to a file should look file-like while still being marked as a link.

Data flow: It creates a real file and a symlink to it, then asks the file system for metadata and compares the result with expected fields. It repeats the same idea for a directory symlink, checking directory flags, file flags, size, symlink status, and timestamps.

Call relations: The test creates a file system context for either local or remote mode, then calls the metadata API. It confirms that both implementations present Unix symlink metadata in the same useful shape.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 6 external calls (new, assert!, assert_eq!, create_dir, write, symlink).

async fn file_system_sandboxed_write_rejects_unwritable_path(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that a read-only sandbox refuses a write. This is the basic rule that a sandbox marked read-only must not allow file creation.

Data flow: It creates a temporary directory and chooses a file path inside it. It builds a read-only sandbox around that directory, tries to write bytes to the file, expects an error, checks that the error is a sandbox denial, and confirms the file was never created.

Call relations: This test uses the shared file system context setup and the sandbox error helper. It is one of the baseline checks that both local and remote file system implementations obey sandbox permissions.

Call graph: calls 4 internal fn (create_file_system_context, read_only_sandbox, assert_sandbox_denied, from_path); 3 external calls (new, bail!, assert!).

async fn file_system_sandboxed_write_allows_explicit_alias_roots(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that a sandbox can allow writes through an explicitly allowed path alias. This prevents over-strict path resolution from rejecting a path the user intentionally allowed.

Data flow: It first looks for a temporary root such as /tmp whose written path differs from its canonical path. If one exists, it creates a temp directory inside it, builds a writable sandbox rooted at the alias path, writes a file, and confirms the file contains the expected bytes.

Call relations: This test depends on alias_root_candidate to decide whether the system can exercise the case. It then uses the normal file system write API to prove local and remote implementations respect explicitly configured alias roots.

Call graph: calls 4 internal fn (create_file_system_context, workspace_write_sandbox, alias_root_candidate, from_path); 2 external calls (assert_eq!, new).

async fn file_system_sandboxed_read_rejects_symlink_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that a read-only sandbox cannot be escaped by following a symlink to an outside directory. This protects against reading files that only appear to be inside the allowed area.

Data flow: It creates an allowed directory, an outside directory, and a secret file outside. Then it places a symlink inside the allowed directory pointing to the outside directory, tries to read the secret through that symlink path, expects failure, and checks the error as a sandbox denial.

Call relations: This test sets up a classic symlink escape attempt and calls the file system read API. It uses assert_sandbox_denied to verify the failure is the intended security block.

Call graph: calls 4 internal fn (create_file_system_context, read_only_sandbox, assert_sandbox_denied, from_path); 5 external calls (new, bail!, create_dir_all, write, symlink).

async fn file_system_sandboxed_read_rejects_symlink_parent_dotdot_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests a trickier path that combines a symlink with .., meaning “go to the parent directory.” The goal is to make sure path cleanup does not accidentally allow a read outside the sandbox.

Data flow: It creates allowed and outside folders, writes a secret file, and adds a symlink inside the allowed folder. It then builds a path like link/../secret.txt, converts it to a path URI, tries to read it under a read-only sandbox, and expects rejection or a safe not-found result.

Call relations: This test calls assert_normalized_path_rejected instead of the standard sandbox-denial helper because path normalization may happen before the file system layer sees the original symlink-shaped path.

Call graph: calls 4 internal fn (create_file_system_context, read_only_sandbox, assert_normalized_path_rejected, from_path); 5 external calls (new, bail!, create_dir_all, write, symlink).

async fn file_system_sandboxed_write_rejects_symlink_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that a writable sandbox cannot write outside its root by using a symlink inside the allowed directory. A writable sandbox must still be limited to the allowed workspace.

Data flow: It creates an allowed directory and an outside directory, then links from inside the allowed directory to the outside one. It tries to write a new file through that link, expects an error, checks the error as sandbox denial, and verifies no outside file was created.

Call relations: This test exercises the file system write API with a malicious-looking destination path. It relies on assert_sandbox_denied to confirm the write was blocked for the right reason.

Call graph: calls 4 internal fn (create_file_system_context, workspace_write_sandbox, assert_sandbox_denied, from_path); 5 external calls (new, bail!, assert!, create_dir_all, symlink).

async fn file_system_sandboxed_write_preserves_existing_hard_link(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that writing through an allowed hard link updates the existing linked file rather than replacing it with a separate new file. A hard link is another name for the same underlying file.

Data flow: It creates a file outside the sandbox and a hard link to that same file inside the allowed directory. It writes new content through the inside hard link, then reads both paths and checks they contain the updated content and still share the same device and inode identifiers.

Call relations: This test calls the sandboxed write API in a case that is allowed because the path itself is inside the workspace. It verifies the implementation does not break Unix hard link identity while enforcing sandbox rules.

Call graph: calls 3 internal fn (create_file_system_context, workspace_write_sandbox, from_path); 6 external calls (new, assert_eq!, create_dir_all, hard_link, metadata, write).

async fn file_system_create_directory_rejects_symlink_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that creating a directory is blocked when the requested path reaches outside the sandbox through a symlink. Directory creation should not be a way to modify outside folders.

Data flow: It creates allowed and outside directories, places a symlink from allowed to outside, then asks the file system to create a directory under that linked path. It expects an error, checks it as sandbox denial, and confirms the outside directory was not modified.

Call relations: This test exercises the create_directory API with sandbox write permissions. It shares the same symlink-escape pattern as the write, copy, read, and remove tests.

Call graph: calls 4 internal fn (create_file_system_context, workspace_write_sandbox, assert_sandbox_denied, from_path); 5 external calls (new, bail!, assert!, create_dir_all, symlink).

async fn file_system_read_directory_rejects_symlink_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that listing a directory is blocked when the directory path is actually a symlink to outside the sandbox. Listing can reveal file names, so it must be protected like reading file contents.

Data flow: It creates an outside directory with a secret file, adds a symlink to that outside directory inside the allowed directory, and tries to read the directory listing through the symlink. It expects failure and checks that the failure is a sandbox denial.

Call relations: This test calls the read-directory API under a read-only sandbox. It uses the shared sandbox-denial helper to keep the expected error rules consistent.

Call graph: calls 4 internal fn (create_file_system_context, read_only_sandbox, assert_sandbox_denied, from_path); 5 external calls (new, bail!, create_dir_all, write, symlink).

async fn file_system_copy_rejects_symlink_escape_destination(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that copying a file is blocked if the destination path escapes the sandbox through a symlink. Without this, a copy operation could write outside the workspace.

Data flow: It creates a source file inside the allowed directory and a symlink from the allowed directory to an outside directory. It tries to copy the source into the outside directory through that symlink, expects an error, checks it as sandbox denial, and confirms no copied file appeared outside.

Call relations: This test exercises the copy API with a safe source and unsafe destination. It is part of the group proving every file operation checks the real destination, not just the written path.

Call graph: calls 4 internal fn (create_file_system_context, workspace_write_sandbox, assert_sandbox_denied, from_path); 6 external calls (new, bail!, assert!, create_dir_all, write, symlink).

async fn file_system_remove_removes_symlink_not_target(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that removing a symlink removes the shortcut itself, not the file it points to. This is important because deleting a link inside the sandbox should not delete an outside target.

Data flow: It creates an outside file and a symlink to it inside the allowed directory. It removes the symlink through the sandboxed file system API, then checks the symlink is gone while the outside file still exists with its original contents.

Call relations: This test calls the remove API in a case where the symlink path is inside the allowed workspace. It verifies the implementation treats the symlink itself as the object to remove.

Call graph: calls 3 internal fn (create_file_system_context, workspace_write_sandbox, from_path); 6 external calls (new, assert!, assert_eq!, create_dir_all, write, symlink).

async fn file_system_copy_preserves_symlink_source(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that copying a symlink copies the symlink itself rather than copying the file it points to. This preserves Unix filesystem structure instead of silently changing meaning.

Data flow: It creates an outside file and a symlink to it inside the allowed directory. It copies that symlink to a new path inside the same allowed directory, then checks the new path is also a symlink and points to the same target.

Call relations: This test exercises the copy API with a symlink as the source. It complements the remove test by confirming symlink-aware operations act on the link itself when appropriate.

Call graph: calls 3 internal fn (create_file_system_context, workspace_write_sandbox, from_path); 7 external calls (new, assert!, assert_eq!, create_dir_all, symlink_metadata, write, symlink).

async fn file_system_remove_rejects_symlink_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that removing a file is blocked if the requested path escapes the sandbox through a symlinked directory. This prevents deleting outside files by disguising their path.

Data flow: It creates an outside file, links an allowed path to the outside directory, then tries to remove the outside file through the link. It expects a sandbox denial and confirms the outside file still contains its original text.

Call relations: This test calls the remove API with an unsafe path. It uses assert_sandbox_denied and belongs to the broader set of tests ensuring every operation respects sandbox boundaries.

Call graph: calls 4 internal fn (create_file_system_context, workspace_write_sandbox, assert_sandbox_denied, from_path); 6 external calls (new, bail!, assert_eq!, create_dir_all, write, symlink).

async fn file_system_copy_rejects_symlink_escape_source(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that copying is blocked if the source path escapes the sandbox through a symlink. Even if the destination is inside the workspace, the operation must not read outside data.

Data flow: It creates a secret outside file and a symlink from the allowed directory to the outside directory. It tries to copy the outside secret into an allowed destination through that symlink path, expects a sandbox denial, and confirms the destination file was not created.

Call relations: This test exercises the copy API with an unsafe source and safe destination. Together with the destination-escape copy test, it proves copy checks both ends of the operation.

Call graph: calls 4 internal fn (create_file_system_context, workspace_write_sandbox, assert_sandbox_denied, from_path); 6 external calls (new, bail!, assert!, create_dir_all, write, symlink).

async fn file_system_copy_preserves_symlinks_in_recursive_copy(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that recursive directory copy preserves symlinks inside the directory tree. Recursive copy means copying a folder and its contents.

Data flow: It creates a source directory with a nested directory and a relative symlink pointing to that nested directory. It copies the source directory recursively, then checks that the copied link is still a symlink and still points to the same relative target text.

Call relations: This test calls the copy API without a sandbox because it is checking copy semantics, not sandbox enforcement. It verifies both local and remote implementations keep symlinks intact during recursive copies.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 6 external calls (new, assert!, assert_eq!, create_dir_all, symlink_metadata, symlink).

async fn file_system_copy_ignores_unknown_special_files_in_recursive_copy(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that recursive directory copy skips special files it does not support, such as a FIFO named pipe, while still copying normal files. A FIFO is a special file used for process-to-process communication, not ordinary stored content.

Data flow: It creates a source directory with a normal text file and a FIFO made with the mkfifo command. It recursively copies the directory, then checks the normal file was copied and the FIFO was not created in the destination.

Call relations: This test uses the external mkfifo command to create a Unix-only special file, then calls the copy API. It documents the intended behavior for special files encountered inside a recursive copy: ignore them rather than fail the whole copy.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 7 external calls (new, bail!, assert!, assert_eq!, new, create_dir_all, write).

async fn file_system_copy_rejects_standalone_fifo_source(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Tests that copying a FIFO directly fails with a clear error. Unlike a FIFO found inside a recursive directory copy, a standalone FIFO source is the whole requested operation, so silently skipping it would be misleading.

Data flow: It creates a FIFO in a temporary directory, then asks the file system to copy that FIFO to a destination. It expects an error and checks both the error kind and the exact message saying copy only supports regular files, directories, and symlinks.

Call relations: This test calls the copy API directly on a special file source. It pairs with the recursive-copy special-file test to define the two intended behaviors: skip unsupported special files inside folders, but reject them when they are the requested source.

Call graph: calls 2 internal fn (create_file_system_context, from_path); 4 external calls (new, bail!, assert_eq!, new).

fn create_directory_junction(target: &Path, alias: &Path) -> Result<()>

Purpose: Creates a Windows directory junction from an alias path to a target path. The tests use it to build the special Windows folder link they need before checking path resolution.

Data flow: It receives two paths: the real target directory and the alias directory to create. It runs the Windows command cmd /C mklink /J <alias> <target>. If Windows reports success, it returns success. If the command fails, it turns the command’s output into a clear error message so the test explains what went wrong.

Call relations: This is the Windows-specific setup tool passed into the shared file system tests. The shared test code calls it when it needs to create a directory alias, and this function hands back either a ready-to-use junction or a failure that stops the test.

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

async fn file_system_canonicalize_resolves_directory_junction(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Checks that normal path canonicalization follows a Windows directory junction to its real target. It runs the same check for both the local and remote file system implementations.

Data flow: It receives the file system implementation being tested. It passes that implementation, along with the junction-creation helper, into the shared test routine. The result is whatever the shared test finds: success if the resolved path is correct, or an error if canonicalization does not follow the junction properly.

Call relations: The test framework calls this function once for the local implementation and once for the remote implementation. This function does not build the whole scenario itself; it delegates the common cross-platform logic to the shared assertion helper and supplies the Windows-specific junction creator.

Call graph: calls 1 internal fn (assert_canonicalize_resolves_directory_alias).

async fn file_system_sandboxed_canonicalize_resolves_directory_junction(
    implementation: FileSystemImplementation,
) -> Result<()>

Purpose: Checks that sandboxed path canonicalization also follows a Windows directory junction correctly. This matters because sandboxing adds safety boundaries, and those boundaries must still understand where a linked directory really points.

Data flow: It receives the file system implementation under test. It sends that implementation and the Windows junction-creation helper to the shared sandboxed test routine. The shared routine performs the setup and checks, then returns success or an error describing the failure.

Call relations: The test framework runs this for both local and remote file systems. This function is the Windows entry point for the sandbox-specific version of the shared directory-alias test, handing off the real checking work to the shared helper.

Call graph: calls 1 internal fn (assert_sandboxed_canonicalize_resolves_directory_alias).

async fn direct_file_system_rejects_non_native_uri_as_invalid_input()

Purpose: This asynchronous test proves that DirectFileSystem rejects a valid-looking but non-native file URI. It is used to make sure the error is reported as invalid input, not as some accidental file-reading failure.

Data flow: It first gets a deliberately non-native PathUri from non_native_uri. It passes that URI into DirectFileSystem.read_file with no sandbox restriction. Instead of expecting file contents back, it expects an error, then checks that the error kind is InvalidInput.

Call relations: During the test run, this function is the main check. It calls non_native_uri to prepare the bad-but-parseable URI, then uses assert_eq! to confirm that DirectFileSystem reports the exact kind of failure the rest of the system can safely understand.

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

fn non_native_uri() -> PathUri

Purpose: This helper creates a file URI that is valid in URI syntax but inappropriate for the operating system running the test. It gives the main test a reliable example of input that should be rejected.

Data flow: It starts with a hard-coded URI string chosen for the current platform: a network-share style URI on Unix, or a Unix-style local path on Windows. It feeds that string into PathUri::parse. If parsing succeeds, it returns the parsed PathUri; if parsing unexpectedly fails, it stops the test with a panic because the fixture itself is broken.

Call relations: The main test calls this helper before trying to read a file. Its job is only to prepare the test input, so the main test can focus on the behavior of DirectFileSystem rather than on the details of constructing the URI.

Call graph: calls 1 internal fn (parse); called by 1 (direct_file_system_rejects_non_native_uri_as_invalid_input); 1 external calls (panic!).

async fn remote_file_system_sends_path_and_sandbox_cwd_uris_without_native_conversion()

Purpose: This is the main test. It proves that RemoteFileSystem::read_file sends path URIs and the sandbox current working directory exactly as URI values, without translating them into the local computer's path style.

Data flow: The test starts by asking record_read_file_params to create a fake WebSocket server that will record two read-file requests. It builds a remote file system client pointed at that server, creates two non-local-looking file URIs, and builds a sandbox context with a deliberately non-native current working directory. It then reads both files through the remote file system. The fake server returns empty data, and the test finally compares what the server captured with the original paths and sandbox information. The expected result is that the sent parameters match exactly.

Call relations: This function drives the whole test scenario. It calls record_read_file_params to stand up the pretend server, calls non_native_cwd to choose a working-directory URI that should not be native to the test machine, then exercises the real remote file system client. The captured server data is the evidence used to confirm the client behaved correctly.

Call graph: calls 8 internal fn (new, websocket_url, new, non_native_cwd, record_read_file_params, from_permission_profile_with_cwd, from_runtime_permissions, restricted); 2 external calls (assert_eq!, vec!).

async fn record_read_file_params(
    expected_requests: usize,
) -> (
    String,
    oneshot::Receiver<Vec<FsReadFileParams>>,
    tokio::task::JoinHandle<()>,
)

Purpose: This helper starts a small local WebSocket server that pretends to be the remote execution server. Its job is to capture the parameters of incoming fs/readFile requests so the test can inspect what the client actually sent.

Data flow: It receives the number of file-read requests it should expect. It opens a local TCP listener on an available port, turns that address into a WebSocket URL for the client, and creates a one-time channel for sending captured data back to the test. In the background, it accepts the client connection, upgrades it to a WebSocket, completes the initialization exchange, then reads the expected number of JSON-RPC read-file requests. For each request, it deserializes the parameters, stores them, and replies with an empty file result. When done, it sends the collected parameters through the channel.

Call relations: The main test calls this before creating the remote file system client. Inside its background server task, it relies on complete_websocket_initialize for the startup handshake, read_jsonrpc_websocket to receive client messages, and write_jsonrpc_websocket to send responses. It hands the test three things: the URL to connect to, a receiver for the captured parameters, and a background task to await.

Call graph: calls 3 internal fn (complete_websocket_initialize, read_jsonrpc_websocket, write_jsonrpc_websocket); called by 1 (remote_file_system_sends_path_and_sandbox_cwd_uris_without_native_conversion); 11 external calls (new, bind, with_capacity, Response, format!, channel, panic!, from_value, to_value, spawn (+1 more)).

fn non_native_cwd() -> PathUri

Purpose: This helper returns a current-working-directory URI that should look foreign to the operating system running the test. That makes it easier to catch unwanted conversion into local path syntax.

Data flow: It checks the compilation target. On Unix-like systems it chooses a Windows/network-share style URI, and on Windows it chooses a Unix-style URI. It parses that string into a PathUri and returns it. If the URI is invalid, the test fails immediately.

Call relations: The main test calls this when building the sandbox context. The returned URI becomes part of the data sent to the fake server, so the final comparison can confirm that even the sandbox working directory was not rewritten.

Call graph: calls 1 internal fn (parse); called by 1 (remote_file_system_sends_path_and_sandbox_cwd_uris_without_native_conversion).

async fn complete_websocket_initialize(websocket: &mut WebSocketStream<TcpStream>)

Purpose: This helper performs the expected startup conversation between the remote file system client and the fake server. It makes the fake server act just enough like a real server for the test to continue.

Data flow: It reads the next JSON-RPC message from the WebSocket and expects it to be an initialize request. It replies with a successful initialization response containing a session ID. Then it reads one more message and expects an initialized notification, which tells the server the client considers startup complete. If either message is not what the test expects, it stops with a failure.

Call relations: The fake server inside record_read_file_params calls this right after accepting the WebSocket connection and before recording file-read requests. It uses read_jsonrpc_websocket to receive the startup messages and write_jsonrpc_websocket to send the initialization response.

Call graph: calls 2 internal fn (read_jsonrpc_websocket, write_jsonrpc_websocket); called by 1 (record_read_file_params); 3 external calls (Response, panic!, to_value).

async fn read_jsonrpc_websocket(websocket: &mut WebSocketStream<TcpStream>) -> JSONRPCMessage

Purpose: This helper reads one JSON-RPC message from a WebSocket connection. It hides the details of WebSocket frames so the test code can think in terms of protocol messages.

Data flow: It waits up to one second for the next WebSocket frame. If the frame contains text, it parses the text as JSON-RPC. If the frame contains binary data, it parses the bytes as JSON-RPC. If it receives WebSocket ping or pong frames, which are connection keep-alive messages, it ignores them and keeps waiting. If the connection closes, times out, or sends an unexpected frame, the test fails.

Call relations: Both complete_websocket_initialize and record_read_file_params call this whenever the fake server needs to receive a message from the client. It is the receiving half of the test's small WebSocket protocol toolkit, paired with write_jsonrpc_websocket.

Call graph: called by 2 (complete_websocket_initialize, record_read_file_params); 6 external calls (from_secs, next, panic!, from_slice, from_str, timeout).

async fn write_jsonrpc_websocket(
    websocket: &mut WebSocketStream<TcpStream>,
    message: JSONRPCMessage,
)

Purpose: This helper sends one JSON-RPC message over a WebSocket connection. It lets the fake server reply to the client in the same format a real remote execution server would use.

Data flow: It takes a JSON-RPC message, converts it into a JSON string, wraps that string in a WebSocket text frame, and sends it through the connection. If serialization or sending fails, the test fails.

Call relations: The fake server uses this in complete_websocket_initialize to answer the client's initialization request, and in record_read_file_params to answer each read-file request. It is the sending half of the test's WebSocket helper pair, complementing read_jsonrpc_websocket.

Call graph: called by 2 (complete_websocket_initialize, record_read_file_params); 3 external calls (send, to_string, Text).

async fn sandboxed_file_system_rejects_non_native_uri_as_invalid_input()

Purpose: This asynchronous test checks that SandboxedFileSystem::read_file rejects a file URI that is not native to the current operating system. It verifies that the rejection is reported as invalid input, not as some later file access failure.

Data flow: It starts by building runtime path information from the current executable, then creates a sandboxed file system from those paths. It builds a restricted permission profile and turns it into a file-system sandbox context. It then passes a deliberately non-native PathUri into read_file. The expected result is an error, and the test checks that the error kind is InvalidInput.

Call relations: This is the main test case in the file. It calls non_native_uri to get the intentionally wrong kind of URI, uses the permission and sandbox constructors to set up a realistic restricted environment, then calls the file system read operation. Finally, it uses an equality assertion to confirm the error is the exact kind the rest of the system should rely on.

Call graph: calls 6 internal fn (new, new, non_native_uri, from_permission_profile, from_runtime_permissions, restricted); 3 external calls (new, assert_eq!, current_exe).

fn non_native_uri() -> PathUri

Purpose: This helper creates a validly parsed file URI that is deliberately not native for the operating system running the test. It lets the test focus on the sandbox behavior instead of repeating platform-specific URI text inline.

Data flow: It chooses one URI string on Unix and a different URI string on Windows. It then asks PathUri::parse to turn that string into a PathUri. If parsing succeeds, it returns the parsed URI. If parsing fails, it panics because the test setup itself is wrong: the URI is supposed to be syntactically valid, just not native.

Call relations: The main test calls this helper when it needs the bad-but-well-formed input. This helper hands back the PathUri that is then passed into SandboxedFileSystem::read_file, where the real behavior under test happens.

Call graph: calls 1 internal fn (parse); called by 1 (sandboxed_file_system_rejects_non_native_uri_as_invalid_input); 1 external calls (panic!).

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

Purpose: This test proves that streaming stops cleanly when a file ends exactly at a chunk boundary. It guards against an easy off-by-one mistake where the server might send an extra empty chunk or wait for more data.

Data flow: It starts a test server, connects to its remote file system, creates a temporary file that is exactly two stream blocks long, and asks for a streamed read. The stream returns chunks of bytes, which the test collects and measures. The expected result is exactly two chunks, each one block in size, with nothing extra after them.

Call relations: This test uses the shared test server setup and the helper that turns a WebSocket URL into an ExecutorFileSystem. It then relies on the normal streaming API rather than the lower-level protocol, so it checks the behavior a real caller would see.

Call graph: calls 3 internal fn (exec_server, connect_file_system, from_path); 4 external calls (new, assert_eq!, write, vec!).

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

Purpose: This test checks that finishing a streamed read frees the server-side file slot it used. Without this, repeated successful reads could slowly exhaust the per-connection open-file limit.

Data flow: It creates one small temporary file, then reads it as a stream more times than the configured open-file limit. Each read is fully consumed before the next begins. The output each time must be the file’s single byte chunk, showing that completed streams do not leave old handles behind.

Call relations: Like the other high-level streaming tests, it starts a test server and connects through connect_file_system. It indirectly exercises the server’s open and close behavior through read_file_stream, rather than calling fs_open and fs_close itself.

Call graph: calls 3 internal fn (exec_server, connect_file_system, from_path); 3 external calls (new, assert_eq!, write).

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

Purpose: This test confirms that streamed file reads refuse platform sandboxing. A sandbox is a set of rules limiting what files a task may access; this feature is not supported for streaming here, so accepting it would be misleading or unsafe.

Data flow: It creates a temporary file and builds a read-only sandbox that permits that temporary directory. It then tries to stream the file while passing that sandbox. Instead of returning bytes, the call must fail with an 'unsupported' error and a clear message saying platform sandboxing is not supported for streaming file reads.

Call relations: The test uses connect_file_system for the client side and read_only_sandbox to build the sandbox context. It focuses on the high-level streaming API’s validation step before any file contents are delivered.

Call graph: calls 4 internal fn (exec_server, connect_file_system, read_only_sandbox, from_path); 4 external calls (new, assert_eq!, panic!, write).

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

Purpose: This Unix-only test makes sure the server rejects a FIFO, also called a named pipe, instead of trying to read it like a normal file. This matters because a FIFO can wait forever until another process writes to it.

Data flow: It creates a temporary FIFO with the operating system’s mkfifo command, converts its path into the project’s path URI form, and then tries both normal full-file reading and streamed reading. Each attempt is wrapped in a short timeout. The expected result is a quick error saying the path is not a file, not a slow hang.

Call relations: The test uses the usual server and file-system connection helper, then exercises both read_file and read_file_stream. It complements the Windows named-pipe test by checking the same safety rule on Unix systems.

Call graph: calls 3 internal fn (exec_server, connect_file_system, from_path); 8 external calls (from_secs, new, bail!, assert_eq!, new, format!, panic!, timeout).

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

Purpose: This Windows-only test checks that Windows named pipes are refused by both full-file and streamed reads. Named pipes are communication channels, not regular files, and reading them as files can block or behave unpredictably.

Data flow: It creates two unique Windows named-pipe paths, one for the full read test and one for the stream test. It asks the remote file system to read each path, with a timeout so the test catches any hang. Both operations must fail quickly with an invalid-input error.

Call relations: This test follows the same safety theme as the Unix FIFO test, but uses Windows named-pipe creation. It uses connect_file_system to reach the server and checks both available file-read paths.

Call graph: calls 4 internal fn (exec_server, connect_file_system, new, from_path); 6 external calls (from_secs, assert_eq!, format!, panic!, new, timeout).

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

Purpose: This Unix-only test verifies that a stream continues reading the file it originally opened, even if the file path is later replaced. In everyday terms, once the server has opened a book, swapping the label on the shelf should not change the pages it is already reading.

Data flow: It writes a file containing one full block plus one extra byte of the letter 'a', starts a stream, and reads the first block. Then it replaces the path on disk with a different file full of the letter 'b'. The remaining stream output must still be the final 'a' byte from the original file, followed by end of stream.

Call relations: This test uses the high-level streaming API through connect_file_system. It checks an important operating-system behavior: the server should stream from the already-open file handle, not reopen the path for every chunk.

Call graph: calls 3 internal fn (exec_server, connect_file_system, from_path); 6 external calls (new, assert_eq!, remove_file, rename, write, vec!).

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

Purpose: This test checks the lower-level file-stream protocol directly: after opening a file handle, the client can read arbitrary byte ranges, not just the next sequential block. That supports flexible clients that may request pieces in a custom order.

Data flow: It starts the server, connects a raw ExecServerClient over WebSocket, writes a ten-byte file, and opens it with a generated handle ID. It then asks for several ranges in a non-sequential order, using different offsets and lengths. The server returns the requested bytes and correctly marks end-of-file when a request reaches past the end. The test finally closes the handle and shuts down the server.

Call relations: Unlike the higher-level streaming tests, this one calls fs_open, fs_read_block, and fs_close directly. It tests the protocol layer beneath read_file_stream, proving that the building blocks used by streaming work even for out-of-order reads.

Call graph: calls 2 internal fn (exec_server, from_path); 7 external calls (new, new_v4, new, assert_eq!, connect_websocket, new, write).

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

Purpose: This test proves that one client connection cannot keep opening file reads forever, and that closing one read frees space for another. This protects the server from a client using too many file handles.

Data flow: It opens the same temporary file repeatedly until it reaches the configured per-connection limit. The next open request must fail with a server error explaining the limit. Then the test closes one previously opened handle and opens the file again, showing that capacity is returned after close.

Call relations: This test talks directly to the protocol through ExecServerClient, because it needs precise control over open handles. It checks the same resource limit that completed_streams_release_handle_capacity exercises indirectly through completed streams.

Call graph: calls 2 internal fn (exec_server, from_path); 8 external calls (new, new_v4, with_capacity, bail!, assert_eq!, connect_websocket, new, write).

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

Purpose: This test confirms that file-read handle IDs have a maximum length. A handle ID is the client-provided name for an open file read; limiting its size prevents wasteful or abusive requests.

Data flow: It starts the server, connects a protocol client, creates a small file, and tries to open it using a handle ID made of 33 characters. The server must reject the request with a clear error saying the handle ID must not exceed 32 bytes.

Call relations: This test works at the fs_open protocol level, where handle IDs are introduced. It pairs with the open-limit test by checking another rule that protects the server before a file read is accepted.

Call graph: calls 2 internal fn (exec_server, from_path); 6 external calls (new, bail!, assert_eq!, connect_websocket, new, write).

fn connect_file_system(websocket_url: &str) -> Result<Arc<dyn ExecutorFileSystem>>

Purpose: This helper creates a test Environment connected to a given exec-server WebSocket URL and returns its file system interface. It keeps the tests short by hiding the repeated setup needed to talk to the server like a normal client.

Data flow: It receives a WebSocket URL string. It builds a test environment configured with that URL, asks the environment for its file system object, and returns that object wrapped in a shared pointer so async test code can use it.

Call relations: The high-level file reading tests call this helper right after starting a test server. It hands them an ExecutorFileSystem, which they then use for read_file or read_file_stream calls without dealing with connection setup each time.

Call graph: calls 1 internal fn (create_for_tests); called by 6 (completed_streams_release_handle_capacity, file_reads_reject_fifo_without_waiting_for_a_writer, file_reads_reject_named_pipes, stream_keeps_reading_the_open_file_after_path_replacement, stream_rejects_platform_sandbox, stream_stops_after_an_exact_block_boundary).

fn read_only_sandbox(path: std::path::PathBuf) -> FileSystemSandboxContext

Purpose: This helper builds a read-only file-system sandbox for one path. It is used to test that streaming rejects platform sandbox settings, even when the sandbox itself would allow reading the file.

Data flow: It receives a filesystem path, verifies and converts it into the project’s absolute-path type, then creates a permission profile that allows read access only to that path and uses restricted network access. The result is a FileSystemSandboxContext ready to pass into file-system calls.

Call relations: stream_rejects_platform_sandbox calls this helper to create the sandbox input for its negative test. The helper delegates to the project’s permission and sandbox constructors so the test uses a realistic sandbox object rather than a fake one.

Call graph: calls 4 internal fn (from_permission_profile, from_runtime_permissions, restricted, from_absolute_path); called by 1 (stream_rejects_platform_sandbox); 1 external calls (vec!).

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

Purpose: This test proves that the client’s buffered HTTP helper always sends a buffered request, even if the caller accidentally sets streaming-related fields. It protects callers from getting streaming behavior when they asked for a complete response body.

Data flow: The test starts a fake server, then calls client.http_request with parameters that include a caller-supplied stream ID and stream_response: true. Before sending the request over the wire, the client rewrites those fields so the fake server receives stream_response: false. The fake server replies with a complete body, and the test checks that the caller receives that full buffered response.

Call relations: This test calls spawn_scripted_exec_server to create the fake WebSocket server, then uses the returned server to connect a real client. Inside the server script, the peer reads the HTTP request and writes back a response. The timeout wrappers keep the test from hanging if the client fails to send or receive the expected messages.

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

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

Purpose: This test checks that streamed HTTP response chunks are matched to the client-generated request ID, not to an unsafe ID supplied by the caller. It also checks that chunks arrive to the caller in the same order the server sent them.

Data flow: The caller starts a streaming HTTP request with its own request ID, but the client replaces it with http-1 before sending it to the fake server. The fake server sends response headers, then three body chunks: hello , world, and !. The test reads from the returned body stream, joins the chunks, and verifies the final body is hello world!; then it starts a second stream and confirms the next generated ID is used.

Call relations: The test relies on spawn_scripted_exec_server for the fake endpoint. The server script uses JsonRpcPeer::read_http_request, write_response, and write_body_delta to act like an exec-server. The public client API under test is http_request_stream, which returns headers first and a separate body stream for later chunks.

Call graph: calls 1 internal fn (spawn_scripted_exec_server); 4 external calls (new, assert_eq!, timeout, vec!).

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

Purpose: This test checks a subtle cleanup case: the server sends the final end-of-body marker before the caller even receives the stream, and then the caller drops the stream without reading it. The client must still remove the old route so the next stream is not confused with the old one.

Data flow: The fake server receives the first streaming request as http-1, immediately sends a terminal body notification saying the body is done, and then sends response headers. The test receives the headers but drops the returned body stream without reading the queued terminal message. It then starts another streaming request and verifies the fake server sees a fresh generated ID, http-2, and the caller receives the second response normally.

Call relations: This test is driven through spawn_scripted_exec_server. The scripted peer sends an out-of-order terminal body notification and then waits for the next request. The client’s stream cleanup behavior is tested only through the public API, without directly inspecting its internal routing table.

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

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

Purpose: This test proves that if a caller cancels a streaming request while it is still waiting for headers, later body chunks for that cancelled request are ignored. This prevents old data from leaking into a later request.

Data flow: The test starts a streaming request and waits until the fake server has seen it as http-1. The caller task is then aborted before headers are returned. A second streaming request is started, which the client sends as http-2. The fake server deliberately sends a stale body chunk for http-1 and then a real body chunk for http-2; the test verifies the caller only receives the fresh http-2 bytes.

Call relations: The test uses a one-shot channel, which is a single-use signal, to coordinate exactly when cancellation happens. It calls spawn_scripted_exec_server for the fake server and tokio::spawn for the cancellable client task. The fake peer then demonstrates that stale notifications no longer have a live route in the client.

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

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

Purpose: This test checks that dropping a returned body stream removes its route, even if the server later sends more chunks for that old stream. That keeps abandoned response data from reaching a new stream.

Data flow: The fake server sends headers for the first request, then waits until the test drops the first body stream. After the drop, it sends a stale body chunk for http-1. The test then starts a second streaming request, which uses http-2, and verifies the body stream contains only the fresh http-2 data.

Call relations: The test uses one-shot channels to coordinate the moment the body stream is dropped and the stale delta is sent. spawn_scripted_exec_server supplies the scripted peer, while the client is exercised through http_request_stream. The story proves cleanup happens when the caller drops the stream, not only when an end marker is read.

Call graph: calls 1 internal fn (spawn_scripted_exec_server); 4 external calls (new, assert_eq!, channel, timeout).

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

Purpose: This test proves that if the shared WebSocket connection closes before a streamed body reaches its final marker, the body stream wakes up with an error. Without this, callers could wait forever.

Data flow: The fake server accepts a streaming request, sends response headers, and then ends its task without sending an end-of-body notification. The client receives the headers and waits for body chunks. When the transport disappears, the body stream returns an error message saying the stream failed because the exec-server transport disconnected.

Call relations: The fake server is created by spawn_scripted_exec_server and only writes the header response. The client’s body stream is then read through recv, and the timeout ensures the test fails quickly if the stream hangs instead of reporting the disconnect.

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

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

Purpose: This test checks that a connection drop is still reported as an error even when the client’s body-chunk queue is already full. It prevents a full queue from hiding the real failure.

Data flow: Before returning headers, the fake server sends exactly enough body chunks to fill the client-side queue for http-1. It then sends headers and disconnects without a final body marker. The test drains all queued chunks and confirms the next result is a transport-disconnect error, not a clean end of stream.

Call relations: The test uses spawn_scripted_exec_server to control the exact order: fill queue, send headers, disconnect. It reads from the public body stream until the error appears. The bail! checks make the test fail if the client incorrectly reports a clean end.

Call graph: calls 1 internal fn (spawn_scripted_exec_server); 4 external calls (new, assert_eq!, bail!, timeout).

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

Purpose: This test checks that if body chunks arrive faster than the client can queue them, the stream ends with an explicit truncation error. That matters because a caller must not mistake a shortened response body for a complete one.

Data flow: The fake server sends more body chunks than the bounded queue can hold before the caller receives the body stream. It then sends headers but keeps the WebSocket connected so the failure is clearly caused by queue overflow, not by disconnection. The test drains whatever chunks made it through and verifies the stream ends with the specific backpressure error.

Call relations: The test creates the fake server with spawn_scripted_exec_server and uses a one-shot channel to keep the server alive until the assertion is complete. It reads the body stream through the public API and uses bail! if overflow is incorrectly presented as a clean end.

Call graph: calls 1 internal fn (spawn_scripted_exec_server); 5 external calls (new, assert_eq!, bail!, channel, timeout).

async fn connect_client(&self) -> Result<ExecServerClient>

Purpose: This helper connects a real ExecServerClient to the fake WebSocket server created for a test. It lets each test exercise the same public connection path that production code would use.

Data flow: It reads the fake server’s WebSocket URL and the fixed test client name, builds connection arguments, and passes them to ExecServerClient::connect_websocket. The result is either a connected client or an error explaining that the test client could not connect.

Call relations: Tests call this after spawn_scripted_exec_server returns a ScriptedExecServer. The helper hands control to the real client connection code, while the fake server task waits to accept that WebSocket connection and complete the initialize handshake.

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

async fn finish(self) -> Result<()>

Purpose: This helper waits for the fake server task to finish and reports any error from it. It is the test cleanup step that makes sure the scripted server did everything it was supposed to do.

Data flow: It consumes the ScriptedExecServer, waits for its background task to join, then unwraps both possible failure layers: the task itself failing, or the script inside the task returning an error. If all is well, it returns success.

Call relations: Tests call this near the end, usually after dropping the client so the WebSocket can close. It connects the test’s main task back to the fake server task and prevents hidden server-side assertion failures from being lost.

async fn spawn_scripted_exec_server(script: F) -> Result<ScriptedExecServer>

Purpose: This helper starts a fake exec-server that accepts one WebSocket client and then runs a caller-provided script. It gives tests a controlled server that can check and send exact JSON-RPC messages.

Data flow: It binds a local TCP listener on an automatically chosen port, builds a WebSocket URL for it, and spawns a background task. That task accepts one client, upgrades the connection to WebSocket, wraps it in JsonRpcPeer, completes the initialize handshake, and then runs the test’s script. The function returns a ScriptedExecServer containing the URL and task handle.

Call relations: All the test functions call this first. It is the bridge between each test’s scripted expectations and the real ExecServerClient connection path. Inside the spawned task it hands off message-level work to JsonRpcPeer::complete_initialize and then to the script supplied by the test.

Call graph: called by 8 (http_request_forces_buffered_request_params, http_response_body_stream_drops_queued_terminal_before_next_generated_id, http_response_body_stream_fails_when_transport_disconnects, http_response_body_stream_ignores_late_deltas_after_cancelled_request, http_response_body_stream_ignores_late_deltas_after_drop, http_response_body_stream_reports_backpressure_truncation, http_response_body_stream_reports_disconnect_when_queue_is_full, http_response_body_stream_uses_generated_ids_and_receives_ordered_deltas); 5 external calls (bind, format!, spawn, timeout, accept_async).

async fn complete_initialize(&mut self) -> Result<()>

Purpose: This helper performs the startup handshake expected by the exec-server protocol. It verifies that the client identifies itself correctly before any HTTP test traffic begins.

Data flow: It reads an initialize request, decodes its parameters into InitializeParams, and checks that the client name and resume session are correct. It sends back an initialize response with a test session ID, then waits for the client’s initialized notification. On success, the fake server is ready for the actual test script.

Call relations: This is called inside spawn_scripted_exec_server before the per-test script runs. It uses read_request, decode_request_params, write_response, and read_notification so later tests do not have to repeat protocol setup.

Call graph: calls 4 internal fn (read_notification, read_request, write_response, decode_request_params); 1 external calls (assert_eq!).

async fn read_http_request(&mut self) -> Result<(RequestId, HttpRequestParams)>

Purpose: This helper reads one http/request JSON-RPC call from the client and turns its JSON parameters into the typed HTTP request data used by the tests. It lets server scripts assert exactly what the client put on the wire.

Data flow: It waits for a JSON-RPC request whose method is http/request. It then decodes the request’s params field into HttpRequestParams and returns both the JSON-RPC request ID and the typed HTTP parameters.

Call relations: Test scripts call this whenever they expect the client to start an HTTP request. Internally it delegates message validation to read_request and JSON decoding to decode_request_params, then hands the request ID back so the script can reply with write_response.

Call graph: calls 2 internal fn (read_request, decode_request_params).

async fn read_request(&mut self, expected_method: &str) -> Result<JSONRPCRequest>

Purpose: This helper reads the next JSON-RPC message and makes sure it is a request with the expected method name. It catches protocol mistakes early with clear test errors.

Data flow: It receives one decoded JSON-RPC message from read_message. If the message is not a request, or if its method does not match the expected method, it returns an error. Otherwise it returns the request object for further decoding or response.

Call relations: complete_initialize uses this to read the startup request, and read_http_request uses it for HTTP calls. It sits one level above raw WebSocket reading and one level below typed request decoding.

Call graph: calls 1 internal fn (read_message); called by 2 (complete_initialize, read_http_request); 1 external calls (bail!).

async fn read_notification(&mut self, expected_method: &str) -> Result<JSONRPCNotification>

Purpose: This helper reads the next JSON-RPC message and makes sure it is a notification with the expected method name. A notification is a one-way message that does not expect a response.

Data flow: It receives one decoded message from read_message. If the message is not a notification, or if the notification method is not the expected one, it returns an error. If it matches, it returns the notification.

Call relations: complete_initialize calls this after sending the initialize response, because the client should then send an initialized notification. It relies on read_message for the actual WebSocket and JSON decoding work.

Call graph: calls 1 internal fn (read_message); called by 1 (complete_initialize); 1 external calls (bail!).

async fn write_response(&mut self, id: RequestId, result: T) -> Result<()>

Purpose: This helper sends a successful JSON-RPC response to a request. Tests use it to return headers or complete HTTP responses from the fake server.

Data flow: It takes a JSON-RPC request ID and a serializable result value. It converts the result into JSON, wraps it in a JSON-RPC response message, and sends it over the WebSocket. The output is success if the message was written, or an error if encoding or writing failed.

Call relations: complete_initialize uses this to answer the startup request, and test scripts use it to answer http/request calls. It hands the final sending step to write_message.

Call graph: calls 1 internal fn (write_message); called by 1 (complete_initialize); 2 external calls (Response, to_value).

async fn write_body_delta(&mut self, delta: HttpRequestBodyDeltaNotification) -> Result<()>

Purpose: This helper sends one streamed HTTP body chunk as a JSON-RPC notification. Tests use it to simulate the exec-server delivering response body data over time.

Data flow: It takes a HttpRequestBodyDeltaNotification, converts it into JSON, wraps it as an http/request/bodyDelta notification, and writes it to the WebSocket. The function returns success or a write/encoding error.

Call relations: The streaming tests call this from their fake server scripts to send fresh chunks, stale chunks, terminal end markers, and overflow traffic. It uses write_message for the shared JSON-RPC sending behavior.

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

async fn read_message(&mut self) -> Result<JSONRPCMessage>

Purpose: This helper reads and decodes one JSON-RPC message from the WebSocket. It is the fake server’s low-level inbox.

Data flow: It waits up to the test timeout for the next WebSocket frame. If the frame is text or binary data, it parses the bytes as JSON-RPC. If the client closes the socket, sends another frame type, or the wait times out, it returns a descriptive error.

Call relations: read_request and read_notification both call this before checking what kind of JSON-RPC message arrived. This keeps raw WebSocket details in one place while higher helpers speak in protocol-level terms.

Call graph: called by 2 (read_notification, read_request); 5 external calls (next, bail!, from_slice, from_str, timeout).

async fn write_message(&mut self, message: JSONRPCMessage) -> Result<()>

Purpose: This helper encodes a JSON-RPC message as text and sends it over the WebSocket. It is the fake server’s low-level outbox.

Data flow: It takes a JSONRPCMessage, serializes it into a JSON string, wraps that string as a WebSocket text message, and sends it with a timeout. It returns success when the message is written or an error if serialization, timeout, or socket writing fails.

Call relations: write_response and write_body_delta both call this after constructing the specific JSON-RPC message they want to send. This keeps the WebSocket writing rules consistent across all fake server replies and notifications.

Call graph: called by 2 (write_body_delta, write_response); 4 external calls (send, to_string, timeout, Text).

fn decode_request_params(request: &JSONRPCRequest) -> Result<T>

Purpose: This helper turns the generic JSON params field from a JSON-RPC request into a strongly typed Rust value. Tests use it so they can compare real protocol messages as normal HTTP or initialize structs.

Data flow: It reads the request’s params value, fails if it is missing, then deserializes that JSON into the requested type. The result is either the typed parameters or an error saying the request parameters were absent or malformed.

Call relations: JsonRpcPeer::complete_initialize uses it to decode initialize parameters, and JsonRpcPeer::read_http_request uses it to decode HTTP request parameters. It is the small conversion step between raw JSON-RPC messages and the test’s typed assertions.

Call graph: called by 2 (complete_initialize, read_http_request); 1 external calls (from_value).

async fn exec_server_http_request_buffers_response_body() -> anyhow::Result<()>

Purpose: This test proves that a normal, non-streaming http/request sends the expected HTTP request and returns the complete HTTP response body in one JSON-RPC response.

Data flow: It starts an exec-server and initializes it, then starts a local TCP listener acting as the HTTP peer. It sends the exec-server a POST request with a header and body, captures what arrives at the local peer, sends back a fixed HTTP response, and finally checks that the exec-server returns the response status, header, and full body.

Call relations: This is one of the top-level test stories. It calls initialize_exec_server to complete setup, accept_http_request to inspect the outgoing HTTP request, respond_with_status_and_headers to provide the fake HTTP response, and wait_for_response to read the JSON-RPC result from the exec-server.

Call graph: calls 5 internal fn (exec_server, accept_http_request, initialize_exec_server, respond_with_status_and_headers, wait_for_response); 5 external calls (bind, assert_eq!, format!, to_value, vec!).

async fn exec_server_http_request_streams_response_body_notifications() -> anyhow::Result<()>

Purpose: This test proves that when response streaming is requested, the exec-server returns headers first and then sends the response body as ordered notifications.

Data flow: It starts and initializes the exec-server, creates a local HTTP peer, and asks for a streamed GET request. The local peer verifies the incoming request and replies using HTTP chunked transfer, meaning the body arrives in pieces. The test then checks that the first JSON-RPC event is the main response with no buffered body, and that later body-delta notifications combine into hello world with a final done marker.

Call relations: As a top-level test, it uses initialize_exec_server for the startup handshake, accept_http_request to observe the request, respond_with_chunked_body to force the streaming path, and collect_response_body_deltas to gather the later notifications.

Call graph: calls 5 internal fn (exec_server, accept_http_request, collect_response_body_deltas, initialize_exec_server, respond_with_chunked_body); 7 external calls (bind, bail!, assert_eq!, format!, from_value, to_value, vec!).

async fn exec_server_http_request_rejects_duplicate_stream_request_ids() -> anyhow::Result<()>

Purpose: This test checks that two active streamed HTTP requests cannot use the same application-level request ID. That matters because streamed body notifications need an ID that clearly says which original request they belong to.

Data flow: It starts a streamed request with request ID stream-dup and keeps its HTTP response open. After the exec-server has accepted that first stream, the test sends a second streamed request with the same ID. It expects a JSON-RPC error saying the ID is already active, then lets the first stream finish and collects its body notifications.

Call relations: This top-level test relies on respond_with_chunked_body_until_finish to keep the first stream alive while the duplicate is attempted. It also uses wait_for_response to confirm the first request started, and collect_response_body_deltas after releasing the held-open stream.

Call graph: calls 6 internal fn (exec_server, accept_http_request, collect_response_body_deltas, initialize_exec_server, respond_with_chunked_body_until_finish, wait_for_response); 8 external calls (bind, new, bail!, assert_eq!, format!, channel, to_value, spawn).

async fn exec_server_http_request_honors_optional_timeout() -> anyhow::Result<()>

Purpose: This test confirms that leaving timeoutMs out means the request is allowed to wait, while setting a very short timeout makes the same kind of slow response fail.

Data flow: It first sends a request with no timeout to a local peer that waits briefly before responding, and checks that the slow body still comes back successfully. Then it sends another request with a 10 millisecond timeout while the peer delays longer, and checks that the exec-server returns an error. If the local peer sees a broken connection afterward, the test treats that as expected because the client timed out and may have closed the socket.

Call relations: This top-level test uses respond_with_status_and_headers for both delayed replies, wait_for_response for the successful no-timeout case, wait_for_error_response for the timed-out case, and is_expected_peer_disconnect to distinguish normal timeout fallout from a real test failure.

Call graph: calls 7 internal fn (exec_server, accept_http_request, initialize_exec_server, is_expected_peer_disconnect, respond_with_status_and_headers, wait_for_error_response, wait_for_response); 9 external calls (from_millis, bind, new, assert!, assert_eq!, format!, to_value, spawn, sleep).

async fn initialize_exec_server(server: &mut ExecServerHarness) -> anyhow::Result<()>

Purpose: This helper performs the startup handshake that the exec-server requires before executor methods such as http/request can be used.

Data flow: It sends an initialize JSON-RPC request containing a test client name, waits for the matching response, then sends an initialized notification. After this, the server is ready for the HTTP request tests.

Call relations: Every top-level test calls this near the beginning. It delegates waiting for the initialize reply to wait_for_response, then hands control back to the test once the server has been put into its ready state.

Call graph: calls 3 internal fn (send_notification, send_request, wait_for_response); called by 4 (exec_server_http_request_buffers_response_body, exec_server_http_request_honors_optional_timeout, exec_server_http_request_rejects_duplicate_stream_request_ids, exec_server_http_request_streams_response_body_notifications); 2 external calls (json!, to_value).

async fn wait_for_response(
    server: &mut ExecServerHarness,
    request_id: RequestId,
) -> anyhow::Result<T>

Purpose: This helper waits until the exec-server sends a JSON-RPC success response for one specific request ID, then turns the response data into the Rust type the caller expects.

Data flow: It receives a server harness and a request ID. It reads events until it finds a response with that ID, extracts the JSON result field, deserializes it into the requested type, and returns that typed value. If the matching event is not actually a response, it reports a test error.

Call relations: The test cases use this whenever they expect success from the exec-server. initialize_exec_server also uses it to wait for the initialization reply before sending the final initialized notification.

Call graph: calls 1 internal fn (wait_for_event); called by 4 (exec_server_http_request_buffers_response_body, exec_server_http_request_honors_optional_timeout, exec_server_http_request_rejects_duplicate_stream_request_ids, initialize_exec_server); 2 external calls (bail!, from_value).

async fn wait_for_error_response(
    server: &mut ExecServerHarness,
    request_id: RequestId,
) -> anyhow::Result<codex_app_server_protocol::JSONRPCErrorError>

Purpose: This helper waits until the exec-server sends a JSON-RPC error response for one specific request ID.

Data flow: It receives a server harness and a request ID. It reads events until it finds an error with that ID, extracts the structured error information, and returns it to the caller for checking.

Call relations: It is used by the timeout test, where success would be wrong. The test then inspects the returned error code and message to make sure the failure came through the expected JSON-RPC path.

Call graph: calls 1 internal fn (wait_for_event); called by 1 (exec_server_http_request_honors_optional_timeout); 1 external calls (bail!).

async fn accept_http_request(listener: &TcpListener) -> anyhow::Result<CapturedHttpRequest>

Purpose: This helper accepts one raw HTTP request from the exec-server and records what was visible on the wire: the request line, headers, and body.

Data flow: It waits up to five seconds for the local TCP listener to receive a connection. It reads the first HTTP line, reads headers until the blank line, uses content-length to know how many body bytes to read, and returns a CapturedHttpRequest containing the socket plus the parsed request details.

Call relations: The top-level tests call this after asking the exec-server to make an HTTP request. It lets the tests verify that the exec-server really sent the expected method, path, headers, and body before a helper writes the fake HTTP response back on the same stream.

Call graph: called by 4 (exec_server_http_request_buffers_response_body, exec_server_http_request_honors_optional_timeout, exec_server_http_request_rejects_duplicate_stream_request_ids, exec_server_http_request_streams_response_body_notifications); 7 external calls (new, new, from_secs, new, accept, timeout, vec!).

async fn respond_with_status_and_headers(
    mut stream: TcpStream,
    status: &str,
    headers: &[(&str, &str)],
    body: &[u8],
) -> anyhow::Result<()>

Purpose: This helper writes a simple fixed-length HTTP response to the captured TCP stream.

Data flow: It takes the open stream, a status such as 201 Created, extra headers, and body bytes. It writes an HTTP/1.1 response with content-length, the provided headers, the body, and flushes the stream so the exec-server can read it.

Call relations: The buffered-response test uses it to send a successful response body. The timeout test uses it from delayed background tasks to simulate a slow HTTP server.

Call graph: called by 2 (exec_server_http_request_buffers_response_body, exec_server_http_request_honors_optional_timeout); 3 external calls (flush, write_all, format!).

fn is_expected_peer_disconnect(err: &anyhow::Error) -> bool

Purpose: This helper decides whether an error from the fake HTTP peer is an expected side effect of the exec-server timing out and closing the connection.

Data flow: It receives an error and walks through its chain of underlying causes. If any cause is an input/output error such as broken pipe, connection reset, or unexpected end of file, it returns true; otherwise it returns false.

Call relations: Only the timeout test calls this. After the exec-server times out, the delayed fake server may fail when trying to write its late response, and this helper prevents that normal disconnect from being treated as a test failure.

Call graph: called by 1 (exec_server_http_request_honors_optional_timeout); 1 external calls (chain).

async fn respond_with_chunked_body(
    mut stream: TcpStream,
    headers: &[(&str, &str)],
    chunks: &[&[u8]],
) -> anyhow::Result<()>

Purpose: This helper writes an HTTP response using chunked transfer encoding, which sends the body in pieces instead of declaring its full length up front.

Data flow: It takes a stream, headers, and a list of byte chunks. It writes HTTP response headers saying the response is chunked, then writes each chunk with its size marker, flushes as it goes, and finally writes the zero-length chunk that means the body is complete.

Call relations: The streaming-response test uses this to make the exec-server exercise its streamed body path. The resulting chunks are later observed through collect_response_body_deltas as JSON-RPC notifications.

Call graph: called by 1 (exec_server_http_request_streams_response_body_notifications); 3 external calls (flush, write_all, format!).

async fn respond_with_chunked_body_until_finish(
    mut stream: TcpStream,
    headers: &[(&str, &str)],
    chunks: &[&[u8]],
    finish_rx: oneshot::Receiver<()>,
) -> anyhow::Result<()>

Purpose: This helper writes the start of a chunked HTTP response, then deliberately keeps the response open until the test says it may finish.

Data flow: It writes chunked response headers and the given chunks, then waits on a one-shot signal. Only after receiving that signal does it write the final zero-length chunk and flush the stream.

Call relations: The duplicate-stream-ID test uses this to keep the first streamed request active while it sends a second request with the same ID. This creates the exact situation where the exec-server should reject the duplicate.

Call graph: called by 1 (exec_server_http_request_rejects_duplicate_stream_request_ids); 3 external calls (flush, write_all, format!).

async fn collect_response_body_deltas(
    server: &mut ExecServerHarness,
    request_id: &str,
) -> anyhow::Result<Vec<HttpRequestBodyDeltaNotification>>

Purpose: This helper gathers streamed response body notifications for one request until it sees the final notification.

Data flow: It repeatedly reads the next JSON-RPC event from the server, checks that it is an http/request/bodyDelta notification, converts the JSON parameters into a typed delta object, and verifies the delta belongs to the expected request ID. It stores each delta and returns the full list when a delta says done.

Call relations: The streaming-response test uses it to check ordering, body contents, and clean completion. The duplicate-ID test uses it after allowing the held-open stream to finish, making sure the original stream still completes properly.

Call graph: calls 1 internal fn (next_event); called by 2 (exec_server_http_request_rejects_duplicate_stream_request_ids, exec_server_http_request_streams_response_body_notifications); 4 external calls (new, bail!, assert_eq!, from_value).

fn response_header(headers: &[HttpHeader], name: &str) -> Option<String>

Purpose: This small helper finds a response header value without caring about uppercase or lowercase differences in the header name.

Data flow: It receives a list of HTTP headers and a name to search for. It scans the list, compares names case-insensitively, and returns a copy of the matching value if one exists.

Call relations: The response-checking assertions use this so the tests do not depend on exact header capitalization. That matters because HTTP header names are meant to be case-insensitive.

Call graph: 1 external calls (iter).

fn hybrid_ik_roundtrip_authenticates_both_endpoints()

Purpose: This test proves that a normal Noise channel handshake works from start to finish. It checks that both endpoints recognize each other, that the initiator’s authorization data reaches the responder, and that encrypted messages can travel both ways afterward.

Data flow: The test starts with two newly generated identities, shared connection context, and an authorization byte string. The initiator creates a handshake request for the responder. The responder reads it, verifies the initiator’s public key and payload, completes the handshake, and sends back a response. The initiator finishes its side, producing two transport objects that can encrypt and decrypt messages. Plain request and response text go in, ciphertext comes out, and the opposite side turns that ciphertext back into the original text.

Call relations: This is the main end-to-end story for the channel. It exercises the identity generation, prologue creation, initiator start, responder request reading, responder completion, initiator finish, and then the transport encryption path in both directions. If this test fails, the basic secure conversation between client and server is broken.

Call graph: calls 3 internal fn (start, generate, read_request); 3 external calls (assert_eq!, assert_ne!, noise_channel_prologue).

fn initiator_rejects_wrong_responder_key()

Purpose: This test checks that a handshake request made for one responder cannot be accepted by a different responder. That matters because otherwise an attacker or misrouted server could pretend to be the intended endpoint.

Data flow: The test creates an initiator, an expected responder, and a separate actual responder. The initiator builds a request using the expected responder’s public key. The actual responder then tries to read that request with its own private identity. The expected result is an error, because the request was not encrypted or addressed for that responder.

Call relations: This test focuses on the responder’s first read of the handshake request. It follows the same setup as a real connection start, but deliberately swaps the responder identity at the receiving side to confirm that the handshake code refuses the mismatch.

Call graph: calls 2 internal fn (start, generate); 2 external calls (assert!, noise_channel_prologue).

fn responder_rejects_mismatched_prologue()

Purpose: This test checks that both sides must agree on the exact connection context before a handshake is accepted. The prologue binds the encrypted channel to a specific environment, registration, and stream, so a message for one stream cannot silently be used for another.

Data flow: The test creates an initiator and responder, then builds two similar but different prologues. The initiator starts the handshake using one prologue. The responder tries to read the request using the other prologue. Because the context does not match exactly, reading the request must fail.

Call relations: This test exercises the same initiator-start and responder-read path as a normal handshake, but with different setup labels on each side. It protects the bigger flow from accepting messages that belong to a different connection context.

Call graph: calls 2 internal fn (start, generate); 2 external calls (assert!, noise_channel_prologue).

fn prologue_encoding_is_stable_and_unambiguous()

Purpose: This test locks down the exact byte format used for the Noise channel prologue. A stable and unambiguous format matters because both sides must turn the same human-readable connection details into exactly the same bytes.

Data flow: The test gives environment, registration, and stream strings to the prologue builder. It receives a byte vector and compares it with a hard-coded expected byte sequence. The expected sequence includes length markers before each part, which prevents two different sets of strings from accidentally producing the same combined bytes.

Call relations: This test focuses only on the prologue-building helper. Other handshake tests rely on that helper indirectly, but this one makes the encoding contract explicit so future edits do not accidentally change the bytes used by the cryptographic handshake.

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

fn transport_rejects_tampered_ciphertext()

Purpose: This test checks that encrypted transport messages cannot be changed without being detected. It proves the channel gives integrity, meaning the receiver can tell if ciphertext was modified after it was sent.

Data flow: The test first completes a normal handshake and creates encrypted transport objects for both sides. The initiator encrypts a request message. The test then flips one bit in the ciphertext, like someone denting a sealed package in transit. When the responder tries to decrypt it, decryption must return an error instead of fake or corrupted plaintext.

Call relations: This test builds on the successful handshake path, then deliberately attacks the transport layer after the secure channel is established. It confirms that the decrypt step refuses modified data rather than passing it upward.

Call graph: calls 3 internal fn (start, generate, read_request); 2 external calls (assert!, noise_channel_prologue).

fn transport_rejects_replayed_ciphertext()

Purpose: This test checks that the same encrypted message cannot be accepted twice. That matters because replaying an old valid message can be dangerous, even if the attacker cannot read or change it.

Data flow: The test completes a normal handshake, then the initiator encrypts one request. The responder decrypts it once and gets the original request text. The test then sends the exact same ciphertext to the responder again. The second decrypt attempt must fail with a transport error because the channel tracks message order and does not allow reuse.

Call relations: This test uses the normal handshake setup and then exercises the transport receiver twice with the same input. It verifies that the secure channel is not just checking message contents, but also enforcing freshness during ongoing communication.

Call graph: calls 3 internal fn (start, generate, read_request); 3 external calls (assert!, assert_eq!, noise_channel_prologue).

fn public_key_validation_rejects_unknown_suite()

Purpose: This test checks that a public key marked with an unknown cryptographic suite is not accepted for a handshake. A suite is the named set of cryptographic choices, and accepting an unknown one could make the system use a key in an unsafe or unsupported way.

Data flow: The test generates a valid public key, serializes it to JSON, changes its suite field to the string "unknown", and deserializes it back into a public key value. It then asks an initiator to start a handshake with that altered key. The result must be an error because the key no longer names the expected Noise channel suite.

Call relations: This test sits at the boundary between stored or transmitted key data and the handshake starter. It makes sure that even if JSON data can be parsed into a public key shape, the actual handshake still validates that the key belongs to the supported suite.

Call graph: calls 1 internal fn (generate); 5 external calls (assert!, Object, from_value, json!, to_value).

fn public_key_serializes_with_expected_suite()

Purpose: This test checks that public keys include the expected suite name when converted to JSON. That makes keys self-describing when they are stored, sent over an API, or read by another part of the system.

Data flow: The test generates an identity, takes its public key, and serializes that key into JSON. It then reads the JSON suite field and compares it with the expected Noise channel suite constant. The output is not a returned value, but a guarantee that serialized keys carry the right label.

Call relations: This test complements the unknown-suite rejection test. One verifies that bad suite labels are refused; this one verifies that normal key serialization writes the correct label in the first place.

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

fn initiator_rejects_oversized_handshake_payload()

Purpose: This test checks that the initiator refuses to put too much extra data into the handshake. This protects the handshake message size limit and prevents unexpectedly large messages from being created.

Data flow: The test generates initiator and responder identities, then creates a payload at the maximum message length. It tries to start a handshake using that payload. Instead of producing a request, the start operation must return a specific invalid-message error saying the handshake payload is too large.

Call relations: This test exercises the initiator’s handshake-start boundary check before any responder is involved. It confirms that oversized authorization or metadata is rejected early, before it can enter the encrypted handshake flow.

Call graph: calls 2 internal fn (start, generate); 2 external calls (assert!, vec!).

fn fragments_and_reassembles_large_jsonrpc_message()

Purpose: This test proves that a large JSON-RPC notification can be split into relay records and then reconstructed exactly. It protects against bugs where big messages are truncated, reordered, or decoded too early.

Data flow: It starts with a JSON-RPC notification whose parameters contain a large string. That message is passed into the framing function, producing a byte stream larger than one record. The test then feeds those bytes to a fresh decoder in record-sized chunks. At the end, the decoder should output one message, and that message must be identical to the original.

Call relations: This test exercises the framing function first, then the decoder that receives framed bytes. It calls on frame_jsonrpc_message to create the outgoing form, then repeatedly uses JsonRpcMessageDecoder as though encrypted records were arriving over the relay.

Call graph: 7 external calls (new, Notification, assert!, assert_eq!, default, json!, frame_jsonrpc_message).

fn rejects_declared_message_length_above_limit_without_payload()

Purpose: This test checks that the decoder refuses a message as soon as its declared length is above the allowed limit. The important point is that it rejects the header alone, before any oversized payload is supplied.

Data flow: It creates a new decoder and builds a four-byte length value that is one byte over the maximum allowed JSON-RPC message size. It feeds only that length header into the decoder. The expected result is a protocol error saying the Noise relay JSON-RPC message has an invalid length.

Call relations: This test goes straight to the decoder because it is checking incoming data validation. It confirms that the decoder does not wait for more bytes when the length claim is already unsafe.

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

fn rejects_oversized_plaintext_record()

Purpose: This test checks that the decoder rejects a single plaintext record that is larger than the allowed Noise record size. This keeps the relay’s record boundary rules strict and predictable.

Data flow: It creates a new decoder and gives it a vector of zero bytes that is one byte longer than the maximum allowed plaintext record. Instead of trying to parse it, the decoder should return a protocol error saying the plaintext record exceeds the maximum length.

Call relations: This test focuses on the decoder’s first line of defense for incoming relay records. It simulates receiving an invalid record and confirms the decoder stops immediately rather than passing oversized data deeper into message parsing.

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

fn releases_ciphertexts_only_in_nonce_order()

Purpose: This test proves that encrypted frames are only released when all earlier sequence numbers have arrived. It checks the basic “wait until the missing first piece shows up” behavior.

Data flow: It starts with an empty OrderedCiphertextFrames buffer. It puts in sequence 1 with the bytes for “second,” and expects no output because sequence 0 is still missing. Then it puts in sequence 0 with the bytes for “first,” and expects the buffer to output both messages in the correct order: first, then second.

Call relations: During the test run, the Rust test framework calls this function. The function creates a fresh OrderedCiphertextFrames value with default, feeds it sample ciphertexts, and uses assert_eq! to compare the actual released frames with the expected order.

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

fn ignores_duplicate_ciphertexts_without_replacing_buffered_record()

Purpose: This test checks that duplicate encrypted frames do not overwrite data that was already buffered. That matters because a repeated sequence number should not be allowed to change what the relay later delivers.

Data flow: It begins with an empty frame buffer. It stores sequence 1 as “first copy,” then tries to store sequence 1 again as “replacement”; both produce no output because sequence 0 has not arrived yet. When sequence 0 arrives as “zero,” the buffer releases “zero” followed by the original “first copy,” proving the duplicate did not replace it. A later duplicate for sequence 0 also produces no output because that sequence has already been processed.

Call relations: The test framework calls this function as part of the test suite. Inside, it relies on OrderedCiphertextFrames::default to start from a clean state, then uses repeated pushes and assert_eq! checks to tell the story of duplicates before and after release.

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

fn rejects_unbounded_reordering()

Purpose: This test confirms that the ordering buffer refuses inputs that would make it grow too far or hold too much data. It protects against memory exhaustion, where a peer could otherwise force the server to keep storing messages that cannot yet be released.

Data flow: It creates an empty OrderedCiphertextFrames buffer. First it tries to add a frame with a sequence number far ahead of the current expected one and expects an error. Then it tries to add a frame whose byte payload is larger than MAX_PENDING_BYTES and also expects an error. The test does not expect any successful output; it is checking rejection.

Call relations: The test framework runs this function with the other tests. The function creates a clean buffer with default, sends it deliberately unsafe inputs, and uses assert! to verify that push reports errors instead of accepting those frames.

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

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

Purpose: This asynchronous test checks that a virtual encrypted stream tells the rest of the relay when it has closed. It is used to catch regressions where a processor exits but no closure notification is sent.

Data flow: The test starts with freshly generated identities for the executor side and the test harness side, then uses them to perform a Noise handshake and create matching encrypted transports. It creates channels for outgoing relay traffic and closed-stream notices, starts a virtual stream with a ConnectionProcessor, encrypts a framed JSON-RPC response, and feeds that encrypted data into the stream. The expected output is a ClosedNoiseVirtualStream message received from the notification channel, carrying stream id stream-1 and instance id 7; the test returns success only if that happens within one second.

Call relations: The test calls the Noise handshake helpers to set up a realistic encrypted connection, uses frame_jsonrpc_message to package a JSON-RPC response the way the relay expects, and constructs the stream through spawn_noise_virtual_stream. It then drives the stream by calling receive_data; after the processor reacts to that input and exits, the test listens for the closure message that the stream is supposed to send back.

Call graph: calls 6 internal fn (start, generate, read_request, frame_jsonrpc_message, new, new); 6 external calls (Response, Integer, assert!, channel, current_exe, spawn_noise_virtual_stream).

fn validate_harness_key(
        &self,
        _harness_public_key: &NoiseChannelPublicKey,
        _authorization: &str,
    ) -> impl std::future::Future<Output = Result<(), ExecServerError>> + Sen

Purpose: This is a test-only validator that records that validation was requested, then waits until the test explicitly releases it. It is used to simulate a real authorization check that is slow or stuck.

Data flow: It receives a harness public key and authorization text, but ignores their contents. It clones shared counters and a notification handle, increments the counter, waits for the notification, and then reports success. The visible output is both the returned success result and the changed call count.

Call relations: The multiplexed environment calls this when a Noise handshake reaches the point where the harness key must be authorized. The tests use its shared counter to know when validation has started, and use its notification only when they want blocked validation tasks to finish.

Call graph: 1 external calls (clone).

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

Purpose: This test proves that one stream waiting on harness-key validation does not stop another stream from starting its own handshake. Without this, a single slow authorization check could freeze all new streams on the same relay.

Data flow: The test creates a local WebSocket pair, generates identities for the environment and harness, and starts the real multiplexed environment with a blocking validator. It then sends two handshake frames on two different stream IDs. It waits until the validator has been called twice, showing both handshakes were allowed to reach validation even though neither validation completed yet. Finally it closes the WebSocket and waits for the environment task to finish.

Call relations: The test drives the same path a harness would use: it starts Noise handshakes, wraps them in relay message frames, encodes those frames, and sends them over the WebSocket. The running environment receives those frames and calls BlockingValidator::validate_harness_key; the test watches the validator’s counter to confirm that the second handshake was not blocked behind the first.

Call graph: calls 6 internal fn (start, generate, noise_channel_prologue, encode_relay_message_frame, new, new); 16 external calls (clone, new, new, from_secs, new, bind, handshake, format!, current_exe, run_multiplexed_environment (+6 more)).

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

Purpose: This test checks that repeatedly sending duplicate handshakes for the same stream is treated as repeated failure, and that enough failures close the whole relay. This protects the environment from a peer that keeps retrying an invalid stream setup forever.

Data flow: The test opens a local WebSocket pair, starts the environment with a blocking validator, and sends a valid handshake for one stream. Once validation is pending, it sends the same encoded handshake again. For each duplicate before the final limit, it expects a reset frame for that stream, meaning the stream was rejected but the physical connection stayed open. After the configured failure budget is used up, another duplicate causes the environment task to end, meaning the physical relay was closed.

Call relations: The test creates Noise handshake bytes with InitiatorHandshake::start, turns them into relay frames, and repeatedly sends the same frame. It reads responses from the harness WebSocket, decodes them with decode_relay_message_frame, and checks that intermediate failures become stream resets. It relies on BlockingValidator::validate_harness_key to keep handshakes pending long enough to make duplicate-handshake behavior observable.

Call graph: calls 7 internal fn (start, generate, noise_channel_prologue, decode_relay_message_frame, encode_relay_message_frame, new, new); 18 external calls (clone, new, new, from_secs, new, bind, bail!, assert_eq!, handshake, format! (+8 more)).

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

Purpose: This test makes sure an authorization field that is larger than the allowed maximum is rejected immediately, before the expensive or external validation step runs. This is a basic resource-safety guard: oversized input should not be handed to deeper logic.

Data flow: The test creates a WebSocket pair and starts the environment with a blocking validator whose call count starts at zero. It builds a Noise handshake request containing authorization data that is one byte too large, sends it as a relay handshake frame, and waits for a binary reset frame in response. It then decodes the reset and checks that the validator was never called.

Call relations: The harness side sends a deliberately oversized handshake frame through the normal relay encoding path. The environment receives it and rejects it before calling BlockingValidator::validate_harness_key. The test confirms this by decoding the returned reset frame and checking the validator call counter remains zero.

Call graph: calls 7 internal fn (start, generate, noise_channel_prologue, decode_relay_message_frame, encode_relay_message_frame, new, new); 18 external calls (clone, new, new, from_secs, new, bind, bail!, assert_eq!, handshake, format! (+8 more)).

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

Purpose: This test checks that repeated corrupted Noise handshake messages eventually close the entire WebSocket relay. A malformed handshake is not just a failed stream setup; repeated malformed input is treated as abusive or broken behavior.

Data flow: The test starts a local harness-to-environment WebSocket connection and generates normal Noise handshake requests. For each attempt, it deliberately flips the last byte of the handshake request, making the cryptographic message invalid, then sends it on a fresh stream ID. After enough malformed handshakes to reach the configured failure limit, the environment task finishes, showing the physical relay was closed.

Call relations: The test uses the regular handshake builder so each message starts out realistic, then corrupts the bytes before encoding the relay frame. The multiplexed environment tries to process these frames and counts them as failed Noise handshakes. Unlike tests that expect a stream reset and continue, this one waits for run_multiplexed_environment to exit after the failure budget is exhausted.

Call graph: calls 6 internal fn (start, generate, noise_channel_prologue, encode_relay_message_frame, new, new); 14 external calls (new, new, from_secs, new, bind, handshake, format!, current_exe, run_multiplexed_environment, spawn (+4 more)).

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

Purpose: This test verifies that sending data on a stream before its handshake has finished is treated as a handshake failure, and repeated early data closes the relay. This prevents a peer from bypassing the required trust check by racing data in too soon.

Data flow: The test opens a local WebSocket pair and starts the environment with a validator that never releases validation. For each attempt, it sends a handshake frame for a new stream and immediately sends a data frame on that same stream with sequence number zero and one byte of payload. Because validation is still pending, that data is too early. After this happens enough times, the environment task ends, meaning the physical relay has been closed.

Call relations: The test sends frames in the same encoded relay format used by real harness traffic: first RelayMessageFrame::handshake, then RelayMessageFrame::data. The blocking validator keeps each handshake from completing, making the following data frame invalid at that moment. The environment counts these repeated protocol violations against the Noise handshake failure budget and eventually shuts down the relay.

Call graph: calls 6 internal fn (start, generate, noise_channel_prologue, encode_relay_message_frame, new, new); 16 external calls (new, new, from_secs, new, bind, data, handshake, format!, current_exe, run_multiplexed_environment (+6 more)).

fn add_auth_headers(&self, headers: &mut HeaderMap)

Purpose: This test helper adds a fixed authorization header to outgoing registry requests. It stands in for real authentication so the tests can check that the registry client sends credentials in the expected shape.

Data flow: It receives a mutable set of HTTP headers. It inserts an Authorization header with the value Bearer registry-token. The same header map then continues on to be used by the HTTP client.

Call relations: The registry client calls this through the AuthProvider interface whenever it prepares a request. In these tests, that lets the mock registry server match requests that include the expected authorization header.

Call graph: 2 external calls (insert, from_static).

fn static_registry_auth_provider() -> SharedAuthProvider

Purpose: This helper creates the shared fake authentication provider used by the tests. It avoids repeating the setup code each time a registry client or remote environment config needs credentials.

Data flow: It takes no input. It wraps StaticRegistryAuthProvider in a shared pointer so multiple pieces of code can hold and use the same provider. It returns that shared authentication provider.

Call relations: The three tests call this when building either a RemoteEnvironmentConfig or an EnvironmentRegistryClient. Those objects later call into StaticRegistryAuthProvider::add_auth_headers when sending registry requests.

Call graph: called by 3 (reconnect_reuses_registration_until_url_is_rejected, validate_harness_key_does_not_expose_error_body, validate_harness_key_requires_explicit_valid_response); 1 external calls (new).

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

Purpose: This test proves that the remote environment reuses an existing registry registration after a normal disconnect, but asks the registry again after the rendezvous URL is explicitly rejected. This matters because needless re-registration is wasteful, while continuing to use a rejected URL could leave the executor stuck.

Data flow: The test starts a local TCP listener to act like the rendezvous WebSocket server and a mock HTTP registry that expects two registration calls. It starts the remote environment task with that registry URL. The first WebSocket connection is accepted and then closed normally, so the task reconnects to the same URL without registering again. The second connection is answered with HTTP 401 Unauthorized, so the task discards that registration. On the next attempt it registers again, then connects successfully. The test verifies the registry saw exactly the expected two registration requests and then stops the background task.

Call relations: This test drives the full remote-environment reconnect loop. It uses static_registry_auth_provider to provide registry credentials, the mock registry to answer registration calls, and a local listener to play the rendezvous server. It indirectly exercises the production registration and reconnect behavior in run_remote_environment.

Call graph: calls 3 internal fn (new, static_registry_auth_provider, new); 13 external calls (from_secs, given, start, new, bind, format!, json!, current_exe, spawn, timeout (+3 more)).

async fn validate_harness_key_requires_explicit_valid_response()

Purpose: This test checks that harness key validation only succeeds when the registry clearly says the key is valid. If the registry responds with valid: false, the executor must reject the key rather than guessing or allowing it.

Data flow: The test creates a fake Noise identity and takes its public key. It sets up a mock registry endpoint that expects a validation request containing the environment id, registration id, harness public key, harness key authorization value, and the fixed bearer token. The mock replies with a successful HTTP response whose JSON says valid: false. The validator sends the request, receives that rejection, and returns a protocol error. The test confirms the error message is the expected safe rejection message.

Call relations: This test builds an EnvironmentRegistryClient with static_registry_auth_provider, then places it inside RegistryHarnessKeyValidator. It calls validate_harness_key directly to check the validator’s fail-closed behavior when the registry gives a clear negative answer.

Call graph: calls 3 internal fn (generate, new, static_registry_auth_provider); 9 external calls (given, start, new, assert!, json!, body_partial_json, header, method, path).

async fn validate_harness_key_does_not_expose_error_body()

Purpose: This test makes sure secret harness authorization text is not leaked into error messages when registry validation fails. That matters because error strings often end up in logs, terminals, or monitoring systems.

Data flow: The test creates a fake Noise public key and configures a mock registry validation endpoint to return HTTP 500 with the sensitive harness authorization string in the response body. The validator sends the validation request and receives the server error. It returns an environment-registry HTTP error with a generic message. The test turns the error into display text and checks that the sensitive authorization string is absent.

Call relations: Like the other validation test, this creates an EnvironmentRegistryClient using static_registry_auth_provider and calls RegistryHarnessKeyValidator::validate_harness_key. Here the focus is the error path: the registry fails, and the validator must hand back a sanitized error instead of exposing the response body.

Call graph: calls 3 internal fn (generate, new, static_registry_auth_provider); 6 external calls (given, start, new, assert!, method, path).

fn add_auth_headers(&self, headers: &mut HeaderMap)

Purpose: This supplies the fixed authorization header that the fake registry expects. It lets the test prove that the remote environment includes registry credentials when it registers and validates itself.

Data flow: It receives a mutable set of HTTP headers. It adds an Authorization header containing the test bearer token. The same header set then travels with the registry request.

Call relations: The helper static_registry_auth_provider wraps this provider so remote_environment_routes_encrypted_exec_server_rpc can pass it into the remote environment configuration. When the remote environment contacts the fake registry, this method is the piece that puts the expected credential on those requests.

Call graph: 2 external calls (insert, from_static).

fn connect_bundle(
        &self,
        _: NoiseChannelPublicKey,
    ) -> BoxFuture<'_, Result<NoiseRendezvousConnectBundle, ExecServerError>>

Purpose: This is a deliberately broken Noise connection provider used to test retry behavior. Every time someone asks it for relay connection details, it records the attempt and returns a protocol error.

Data flow: It receives the public key for the Noise channel, but ignores it because this provider is only a test double. It increases an atomic counter, which is a thread-safe number, and returns an error saying the registry connection failed. Nothing connects successfully.

Call relations: noise_environment_refreshes_bundle_for_each_connection_attempt installs this provider into an environment manager. Each failed backend start calls into this provider, and the test later checks the counter to confirm that two start attempts caused two fresh bundle requests.

Call graph: 1 external calls (Protocol).

fn static_registry_auth_provider() -> codex_api::SharedAuthProvider

Purpose: This small helper creates the shared authentication provider used by the registry-related test. It keeps the setup readable by hiding the wrapping needed to share the provider safely.

Data flow: It takes no input. It creates a StaticRegistryAuthProvider and places it inside a shared reference-counted pointer so other parts of the test can pass it around. It returns that shared authentication provider.

Call relations: remote_environment_routes_encrypted_exec_server_rpc calls this while building the remote environment configuration. The returned provider is later used by the remote environment when it talks to the fake registry.

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

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

Purpose: This test checks that a Noise-backed environment does not reuse a failed relay connection setup forever. Each new process start attempt should ask for a new connection bundle.

Data flow: It starts with a counter at zero and an environment manager with no preloaded environments. It adds a fake Noise environment whose provider always fails, then tries to start two simple processes. Both starts return the expected protocol error, and the counter must end at two.

Call relations: This test drives the environment manager and backend start path directly. Its key collaborator is FailingNoiseConnectProvider::connect_bundle, which records every bundle request and returns the controlled failure that the test expects.

Call graph: calls 3 internal fn (without_environments, new, from_path); 9 external calls (clone, new, new, new, assert!, assert_eq!, format!, current_dir, vec!).

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

Purpose: This is the full end-to-end relay encryption test. It proves that a real remote environment and a real client can connect through a fake relay, run commands, transfer a large file response, and keep relay data encrypted.

Data flow: It creates a local TCP listener to act like the WebSocket relay and a mock HTTP registry that returns connection instructions. It starts the remote environment, accepts its WebSocket, extracts the executor public key from the registry request, and starts a client using a generated Noise identity. It then proxies frames between the client and environment, sends an exec request, reads a large file, checks the returned bytes, and finally inspects captured relay frames to make sure plaintext request details are not visible.

Call relations: This test is the main story in the file. It calls static_registry_auth_provider during setup, accept_websocket for both sides of the fake relay, registered_executor_public_key to learn what key the environment registered, proxy_relay_frames to shuttle messages between the two WebSockets, and assert_relay_data_is_encrypted after the real RPC calls have crossed the relay.

Call graph: calls 11 internal fn (generate, from, new, new, current_test_binary_helper_paths, accept_websocket, assert_relay_data_is_encrypted, proxy_relay_frames, registered_executor_public_key, static_registry_auth_provider (+1 more)); 23 external calls (clone, new, new, given, start, new, new, bind, new, new (+13 more)).

async fn accept_websocket(
    listener: &TcpListener,
    role: &str,
) -> Result<WebSocketStream<TcpStream>>

Purpose: This helper waits for one side of the test connection to arrive and upgrades it into a WebSocket. A WebSocket is a long-lived connection that can send messages both ways, like a phone call instead of a single letter.

Data flow: It receives the TCP listener for the fake relay and a human-readable role name such as environment or harness. It waits, with a timeout, for a TCP connection, then performs the WebSocket handshake. It returns the ready-to-use WebSocket stream or an error explaining which role failed to connect.

Call relations: remote_environment_routes_encrypted_exec_server_rpc calls this twice: first to accept the remote environment side, then to accept the harness client side. The returned streams are handed to proxy_relay_frames so the fake relay can pass messages between them.

Call graph: called by 1 (remote_environment_routes_encrypted_exec_server_rpc); 3 external calls (accept, timeout, accept_async).

async fn registered_executor_public_key(registry: &MockServer) -> Result<NoiseChannelPublicKey>

Purpose: This helper pulls the executor public key out of the fake registry’s recorded registration request. The client needs this key to set up the encrypted Noise channel with the remote environment.

Data flow: It reads all HTTP requests captured by the mock registry, finds the registration request, parses its JSON body, and extracts the executor_public_key field. It returns that key in the strongly typed form expected by the client connection setup.

Call relations: remote_environment_routes_encrypted_exec_server_rpc calls this after the remote environment registers itself. The returned key is placed into the Noise rendezvous connection bundle used by the client.

Call graph: called by 1 (remote_environment_routes_encrypted_exec_server_rpc); 3 external calls (received_requests, from_slice, from_value).

async fn proxy_relay_frames(
    mut environment: WebSocketStream<TcpStream>,
    mut harness: WebSocketStream<TcpStream>,
    captured_frames: Arc<Mutex<Vec<Vec<u8>>>>,
) -> Result<()>

Purpose: This is the fake relay’s message pump. It copies WebSocket messages from the environment to the harness and from the harness to the environment, while saving binary frames so the test can inspect them later.

Data flow: It receives two open WebSocket streams and a shared list for captured frame bytes. In a loop, it waits for a message from either side. Each received message is optionally copied into the capture list if it is binary, then forwarded to the opposite side. It finishes when either stream closes or returns an error if forwarding fails.

Call relations: remote_environment_routes_encrypted_exec_server_rpc starts this helper as a background task after both WebSocket sides are connected. Inside the loop it calls capture_binary_frame before forwarding, so assert_relay_data_is_encrypted later has raw relay data to examine.

Call graph: called by 1 (remote_environment_routes_encrypted_exec_server_rpc); 1 external calls (select!).

fn capture_binary_frame(captured_frames: &Mutex<Vec<Vec<u8>>>, message: &Message)

Purpose: This helper records the raw bytes of relay messages that are sent as binary WebSocket frames. Text or other WebSocket message types are ignored because the relay protocol data being checked is binary.

Data flow: It receives the shared captured-frame list and one WebSocket message. If the message is binary, it locks the list, copies the bytes, and appends them. If the lock was previously poisoned by a panic, it still recovers the inner list so the test can continue collecting evidence.

Call relations: proxy_relay_frames calls this for every message traveling in either direction. The bytes it saves are later read by assert_relay_data_is_encrypted to verify that relay payloads do not expose plaintext RPC details.

fn assert_relay_data_is_encrypted(captured_frames: &Mutex<Vec<Vec<u8>>>) -> Result<()>

Purpose: This helper checks that captured relay data frames do not contain readable request names or client identifiers. It is the test’s final privacy check: the relay may move data, but it should not understand it.

Data flow: It locks the shared list of captured binary frames, decodes each one as a relay message frame, and looks only at frames that carry data payloads. For each data payload, it converts the bytes to a lossy string for searching and asserts that words such as initialize, process/start, and noise-relay-test are absent. It also requires that at least several data frames were seen, so the check is meaningful.

Call relations: remote_environment_routes_encrypted_exec_server_rpc calls this after successful exec and file-read requests have crossed the fake relay. It relies on proxy_relay_frames and capture_binary_frame having saved the raw frames during the earlier message exchange.

Call graph: called by 1 (remote_environment_routes_encrypted_exec_server_rpc); 3 external calls (from_utf8_lossy, assert!, decode).

fn reassembles_client_message_chunks()

Purpose: This test proves that a client message split into two chunks can be put back together into the original JSON-RPC message. It matters because real client messages may be too large for one transport packet, but the rest of the app should still receive one normal message.

Data flow: It starts with a JSON-RPC notification and serializes it into bytes. Those bytes are split in half, wrapped into two chunk-style client envelopes, and fed into a fresh reassembler. The first chunk produces a waiting state; the second produces a rebuilt envelope whose client id, stream id, sequence id, cursor, and message contents are checked against the original.

Call relations: During the test, it uses chunk_envelope to make realistic chunk packets and then asks the reassembler to observe them in order. If the reassembler returns a complete message, the test compares it with the original; if it stays pending or drops the data, the test fails because this is the happy path that must work.

Call graph: calls 1 internal fn (chunk_envelope); 8 external calls (Notification, new, new, default, assert!, assert_eq!, panic!, to_vec).

fn splits_large_server_messages_into_wire_chunks()

Purpose: This test checks that a server message larger than the transport limit is broken into multiple smaller messages before being sent. Without this, a large notification could exceed the remote-control wire limit and fail in transit.

Data flow: It builds a server envelope containing a deliberately large configuration warning. That envelope goes into split_server_envelope_for_transport, which returns a list of transport-ready envelopes. The test then confirms there is more than one segment, every segment is marked as a server message chunk, each keeps the original sequence id, and each serialized segment fits within the maximum byte size.

Call relations: This test exercises the outgoing side of the segmentation system. It hands a large ServerEnvelope to split_server_envelope_for_transport, then inspects the returned pieces as the transport layer would see them before sending.

Call graph: calls 1 internal fn (split_server_envelope_for_transport); 6 external calls (new, ConfigWarning, AppServerNotification, new, new, assert!).

fn invalidates_incomplete_stream_assemblies()

Purpose: This test makes sure an unfinished message assembly can be canceled for a specific client stream. This is important when a stream ends or is reset, because leftover chunks from that old stream should not later create a fake complete message.

Data flow: It creates a two-part client message and feeds only the first chunk into the reassembler, which leaves the message pending. It then invalidates that client and stream. When the second chunk arrives afterward, the reassembler drops it instead of finishing the old message.

Call relations: The test follows the stream-reset path: start an assembly, call the reassembler’s stream invalidation step, then send what would have completed the message. The expected handoff is no handoff at all; the stale chunk is dropped before it can be forwarded.

Call graph: 6 external calls (Notification, new, new, default, assert!, to_vec).

fn resets_incomplete_client_assembly_when_stream_changes()

Purpose: This test checks what happens when the same client starts assembling a message on one stream, then begins a newer message on another stream. The newer stream should replace the old unfinished work, so the old stream cannot complete later.

Data flow: It creates one serialized message and uses the first half to start an assembly on stream 1. Then it starts another assembly for the same client on stream 2 with a newer sequence id. When stream 2’s second chunk arrives, the message rebuilds successfully; when stream 1’s second chunk arrives later, it is dropped.

Call relations: The test uses chunk_envelope to create chunk packets for two streams and feeds them to the same reassembler. It demonstrates that the reassembler follows the newer stream and forwards only the replacement assembly, while rejecting the older stream’s late completion.

Call graph: calls 1 internal fn (chunk_envelope); 8 external calls (Notification, new, new, default, assert!, assert_eq!, panic!, to_vec).

fn ignores_stale_chunks_without_dropping_newer_assembly()

Purpose: This test proves that an old chunk with a lower sequence id is ignored without damaging a newer message that is already being assembled. This protects users from out-of-order network delivery, where an old packet may arrive after a newer one has started.

Data flow: It starts a pending assembly for sequence id 8. Then it sends a chunk for sequence id 7, which is older and should be dropped. Finally, it sends the second chunk for sequence id 8, and the reassembler still completes and forwards the newer message.

Call relations: The test puts the reassembler in the middle of a valid newer assembly, then introduces a stale packet. The key relationship is that the stale observation must stop there as Dropped; it must not reset or corrupt the pending newer work that later becomes Forward.

Call graph: 6 external calls (Notification, new, new, default, assert!, to_vec).

fn ignores_invalid_stale_chunks_without_dropping_newer_assembly()

Purpose: This test checks a stricter case: even if an old chunk is malformed or empty, it should still be ignored without harming the current newer assembly. Bad old data should not be able to knock a valid message off track.

Data flow: It begins assembling sequence id 8 from a valid first chunk. It then feeds an invalid empty chunk for older sequence id 7, which the reassembler drops. After that, the valid second chunk for sequence id 8 still completes the message and is forwarded.

Call relations: The test exercises the defensive path for stale and invalid data. The reassembler is expected to reject the old bad chunk immediately and continue holding the newer partial message until the matching final chunk arrives.

Call graph: 6 external calls (Notification, new, new, default, assert!, to_vec).

fn ignores_invalid_duplicate_chunks_without_dropping_current_assembly()

Purpose: This test verifies that a bad duplicate of a chunk already seen does not destroy the current assembly. That matters because duplicate packets can happen, and a corrupted repeat should not erase good data already collected.

Data flow: It starts assembling sequence id 8 with a valid first chunk. It then sends another chunk with the same sequence id and same segment id, but with empty invalid data, which is dropped. The proper second chunk is then accepted, and the full message is forwarded.

Call relations: The test focuses on duplicate handling inside the reassembler. It shows that the reassembler can reject the duplicate bad chunk while keeping the earlier valid chunk, so the next correct piece can still complete the message.

Call graph: 6 external calls (Notification, new, new, default, assert!, to_vec).

fn chunk_envelope(
    client_id: ClientId,
    stream_id: Option<StreamId>,
    seq_id: u64,
    segment_id: usize,
    segment_count: usize,
    message_size_bytes: usize,
    chunk: &[u8],
) -> Cli

Purpose: This helper builds a realistic client envelope that contains one base64-encoded message chunk. The tests use it so they can focus on reassembly behavior instead of repeating packet-building code.

Data flow: It receives a client id, optional stream id, sequence id, segment number, total segment count, total message size, and raw chunk bytes. It base64-encodes the raw bytes, places the chunk metadata into a ClientMessageChunk event, attaches the client and stream information, and returns a ClientEnvelope with no cursor.

Call relations: The reassembly tests call this helper when they need to simulate chunks arriving from a client. It hands back envelopes shaped like transport input, which are then passed into the reassembler for observation.

Call graph: called by 2 (reassembles_client_message_chunks, resets_incomplete_client_assembly_when_stream_changes).

fn remote_control_auth_manager() -> Arc<AuthManager>

Purpose: Creates a ready-to-use fake ChatGPT authentication manager for tests. Tests use it when they need remote control to behave as if a signed-in user is available.

Data flow: It starts with no input, builds dummy ChatGPT credentials, wraps them in an AuthManager, and returns a shared pointer to that manager. Nothing is written to disk.

Call relations: Many remote-control tests call this during setup before starting the remote-control transport. It relies on the test-support auth builder and the dummy auth constructor so the tests can focus on remote-control behavior instead of real login.

Call graph: calls 2 internal fn (auth_manager_from_auth, create_dummy_chatgpt_auth_for_testing); called by 12 (ephemeral_enable_preserves_durable_preference, explicit_disabled_start_ignores_persisted_enable, managed_disable_overrides_startup_and_persisted_enablement, plain_start_resolves_persisted_remote_control_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, remote_control_start_allows_remote_control_invalid_url_when_disabled, remote_control_start_reports_missing_state_db_as_disabled_when_enabled, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages (+2 more)).

fn remote_control_auth_manager_with_home(codex_home: &TempDir) -> Arc<AuthManager>

Purpose: Creates a fake authenticated user tied to a specific temporary Codex home directory. Tests use it when the auth manager must read or cooperate with files stored under that test directory.

Data flow: It receives a temporary directory, creates dummy ChatGPT credentials, points the auth manager at that directory path, and returns the shared AuthManager.

Call relations: Persistence-heavy tests call this before starting remote control. It hands the temporary home path to the auth test helper so later enrollment and refresh logic can operate in a realistic per-home environment.

Call graph: calls 2 internal fn (auth_manager_from_auth_with_home, create_dummy_chatgpt_auth_for_testing); called by 6 (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, remote_control_stdio_mode_waits_for_client_name_before_connecting); 1 external calls (path).

fn remote_control_auth_dot_json(account_id: Option<&str>) -> AuthDotJson

Purpose: Builds an in-memory auth.json-style record for tests, optionally including an account id. This lets tests simulate a user whose auth is present but whose account id may or may not be known yet.

Data flow: It receives an optional account id, creates a fake unsigned JWT-like token payload, parses that token into ChatGPT claims, and returns an AuthDotJson record containing access and refresh tokens plus the optional account id.

Call relations: Tests that save and reload auth files use this to switch between accounts or add a missing account id. It feeds saved auth data into AuthManager so remote control can react as if real credentials changed.

Call graph: calls 1 internal fn (parse_chatgpt_jwt_claims); called by 2 (persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_waits_for_account_id_before_enrolling); 4 external calls (now, format!, json!, to_vec).

async fn remote_control_state_runtime(codex_home: &TempDir) -> Arc<StateRuntime>

Purpose: Creates the test state database used to store remote-control enrollment records and preferences. Without it, tests could not check durable enablement or saved server identity behavior.

Data flow: It receives a temporary Codex home directory, initializes a StateRuntime under that path with a test provider name, and returns the initialized shared state runtime.

Call relations: Most tests call this before starting remote control or before writing saved enrollment rows. The remote-control code later reads from and writes to this same state runtime.

Call graph: calls 1 internal fn (init); called by 19 (ephemeral_enable_preserves_durable_preference, explicit_disabled_start_ignores_persisted_enable, managed_disable_overrides_startup_and_persisted_enablement, persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, plain_start_resolves_persisted_remote_control_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, 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 (+9 more)); 1 external calls (path).

async fn plain_start_resolves_persisted_remote_control_preference()

Purpose: Checks how startup behaves when the desired remote-control state is unknown. It verifies that saved preferences are interpreted correctly: explicitly enabled stays enabled, while disabled, unset, or missing becomes disabled.

Data flow: The test creates several saved enrollment records with different preference values, starts a RemoteControlWebsocket object with an unknown desired state, asks it to resolve that state for each case, and checks the resulting desired-state watch value.

Call relations: The async test runner invokes this test. It uses fake auth, a temporary state runtime, URL normalization, and the test server name helper to build the same pieces that production startup would use.

Call graph: calls 7 internal fn (new, normalize_remote_control_url, remote_control_auth_manager, remote_control_state_runtime, test_server_name, new, new); 9 external calls (new, new, new, new, assert!, assert_eq!, format!, channel, channel).

async fn explicit_disabled_start_ignores_persisted_enable()

Purpose: Verifies that an explicit “start disabled for this run” mode wins over a saved enabled preference. This prevents the app from reconnecting just because an old setting said remote control was enabled.

Data flow: The test saves an enabled enrollment, starts remote control in DisabledEphemeral mode, checks that the desired state is disabled, and confirms the saved enrollment record was not changed.

Call relations: The test runner calls it. It prepares fake state and auth, starts remote control through the public start function, then cancels the shutdown token to stop the background task cleanly.

Call graph: calls 3 internal fn (normalize_remote_control_url, remote_control_auth_manager, remote_control_state_runtime); 4 external calls (new, new, assert_eq!, channel).

async fn managed_disable_overrides_startup_and_persisted_enablement()

Purpose: Checks that a managed policy disabling remote control overrides both startup requests and saved enablement. This matters for environments where administrators or requirements forbid the feature.

Data flow: The test saves an enabled enrollment, starts remote control with a disabled-by-requirements policy, then checks status, permission errors, unchanged persistence, and that no backend connection is attempted.

Call relations: The test runner calls it. It uses the local listener URL helper, fake auth, and state setup, then exercises the RemoteControlHandle methods that users or RPC commands would normally call.

Call graph: calls 4 internal fn (normalize_remote_control_url, remote_control_auth_manager, remote_control_state_runtime, remote_control_url_for_listener); 8 external calls (new, from_millis, bind, new, assert!, assert_eq!, channel, timeout).

fn remote_control_url_for_listener(listener: &TcpListener) -> String

Purpose: Builds a remote-control base URL pointing at a local test TCP listener. Tests use it so the real remote-control code connects to the fake server created inside the test.

Data flow: It receives a TcpListener, reads the listener’s local address, formats that address into an HTTP backend-api URL, and returns the URL string.

Call relations: Many tests call this immediately after binding a local listener. The returned URL is passed into remote-control startup so later helper functions can accept and inspect the resulting requests.

Call graph: called by 17 (managed_disable_overrides_startup_and_persisted_enablement, persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, 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, remote_control_start_allows_missing_auth_when_enabled (+7 more)); 2 external calls (local_addr, format!).

fn test_server_name() -> String

Purpose: Returns the current machine hostname in the same trimmed string form expected by remote-control status and enrollment code. Tests use it when comparing server-name fields.

Data flow: It reads the operating system hostname, converts it to text, trims surrounding whitespace, and returns that string.

Call relations: Setup helpers and status assertions call it whenever expected notifications or enrollment objects need the local server name.

Call graph: called by 5 (plain_start_resolves_persisted_remote_control_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_handle_with_current_enrollment, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_preserves_stale_enrollment_when_reenrollment_fails); 1 external calls (gethostname).

fn remote_control_handle_with_current_enrollment(
    remote_control_url: &str,
    auth_manager: Arc<AuthManager>,
) -> RemoteControlHandle

Purpose: Creates a standalone RemoteControlHandle that already has an active enrollment. This lets tests exercise handle methods without starting a full network task.

Data flow: It receives a remote-control URL and auth manager, creates desired-state and status watch channels, normalizes the URL, builds an enrollment with a future expiry and token, and returns a RemoteControlHandle containing those pieces.

Call relations: The ephemeral-enable test calls this to get a handle with realistic internal state. It uses URL normalization and the server-name helper, but does not contact a backend.

Call graph: calls 3 internal fn (new, normalize_remote_control_url, test_server_name); called by 1 (ephemeral_enable_preserves_durable_preference); 4 external calls (new, from_unix_timestamp, new, channel).

async fn ephemeral_enable_preserves_durable_preference()

Purpose: Checks that temporarily enabling remote control does not erase a saved durable preference. It also verifies that ephemeral enable from a disabled state records no durable preference.

Data flow: The test builds a handle, attaches a test state database, sets the desired state to durably enabled, calls ephemeral enable, and checks the preference is preserved. Then it resets to disabled, enables ephemerally again, and checks the preference is absent.

Call relations: The test runner calls it. It depends on the handle-construction helper, fake auth, and state runtime to focus on the RemoteControlHandle state transition.

Call graph: calls 3 internal fn (remote_control_auth_manager, remote_control_handle_with_current_enrollment, remote_control_state_runtime); 2 external calls (new, assert_eq!).

fn remote_control_server_token_response(
    server_id: &str,
    environment_id: &str,
    remote_control_token: &str,
) -> serde_json::Value

Purpose: Creates the JSON body a fake backend returns after enrollment or token refresh. It keeps repeated test responses consistent.

Data flow: It receives a server id, environment id, and remote-control token, combines them with a fixed far-future expiry time, and returns a JSON value.

Call relations: Enrollment, refresh, reconnect, and routing tests call this before responding to captured HTTP requests. The response is then sent through respond_with_json to drive the production code forward.

Call graph: called by 13 (persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, 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, remote_control_stdio_mode_waits_for_client_name_before_connecting, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages (+3 more)); 1 external calls (json!).

async fn expect_remote_control_status(
    status_rx: &mut watch::Receiver<RemoteControlStatusChangedNotification>,
    expected_status: Option<RemoteControlConnectionStatus>,
    expected_environment

Purpose: Waits for the next remote-control status notification and checks important fields. It helps tests avoid racing ahead before the background task has reported a new state.

Data flow: It receives a watch receiver, an optional expected connection status, and an optional expected environment id. It waits up to five seconds for a change, reads the latest notification, and asserts the status, server name, installation id, and environment id.

Call relations: Connection and enrollment tests call this after accepting backend requests or WebSocket connections. It watches the status channel published by the remote-control handle.

Call graph: called by 9 (remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_reenrolls_after_explicit_missing_server_404, remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages, remote_control_transport_reconnects_after_disconnect, remote_control_transport_refreshes_server_token_after_websocket_unauthorized); 5 external calls (from_secs, assert_eq!, borrow, changed, timeout).

async fn expect_remote_control_status_snapshot(
    status_rx: &mut watch::Receiver<RemoteControlStatusChangedNotification>,
    expected_status: RemoteControlStatusChangedNotification,
)

Purpose: Waits until the status channel exactly matches a given notification. This is useful when several status changes may happen quickly and the test cares about one exact state.

Data flow: It receives a watch receiver and an expected notification. If the current value already matches, it returns; otherwise it waits for changes until the exact snapshot appears or the timeout fails.

Call relations: Enable/disable and generic-404 tests call this when they need to observe a precise connected, connecting, or disabled notification rather than just the next event.

Call graph: called by 2 (remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404); 6 external calls (from_secs, clone, assert!, borrow, changed, timeout).

async fn remote_control_transport_manages_virtual_clients_and_routes_messages()

Purpose: Tests the core WebSocket transport behavior: remote backend clients become app-server connections, incoming JSON-RPC messages are delivered, outgoing server messages are sent back, and clients can close.

Data flow: The test starts remote control, accepts enrollment and WebSocket setup, sends ping and client-message envelopes from the fake backend, reads transport events from an internal channel, sends an outgoing notification through the provided writer, and checks the WebSocket JSON events.

Call relations: The test runner calls it as a full integration-style scenario. It uses the HTTP/WebSocket accept helpers, client-event sender, server-event reader, fake auth, fake state, and token response helper to simulate the whole backend conversation.

Call graph: calls 11 internal fn (new, normalize_remote_control_url, accept_http_request, accept_remote_control_connection, expect_remote_control_status, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json (+1 more)); 15 external calls (new, from_secs, ConfigWarning, bind, new, Notification, Request, Integer, AppServerNotification, new (+5 more)).

async fn remote_control_transport_reconnects_after_disconnect()

Purpose: Verifies that remote control reconnects after the backend WebSocket disconnects. This keeps remote control available through ordinary network drops.

Data flow: The test starts remote control, completes enrollment, accepts a first WebSocket and closes it, accepts a second WebSocket, sends an initialize message, and checks that a new connection-open event reaches the transport channel.

Call relations: The test runner invokes it. It depends on the backend-connection capture helper to inspect authorization headers across reconnects and on status waiting to confirm the reconnected environment.

Call graph: calls 9 internal fn (accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, send_client_event); 11 external calls (new, from_secs, bind, new, Request, Integer, new, assert_eq!, json!, panic! (+1 more)).

async fn remote_control_transport_refreshes_server_token_after_websocket_unauthorized()

Purpose: Checks that a 401 Unauthorized response during WebSocket connection causes the server token to be refreshed before retrying. This prevents stale server tokens from permanently breaking remote control.

Data flow: The test enrolls with an initial token, rejects the first WebSocket HTTP upgrade with 401, captures the refresh request, returns a new token, and verifies the next WebSocket uses the refreshed token.

Call relations: The test runner calls it. It uses raw HTTP request capture for the failed upgrade and refresh request, then the WebSocket backend accept helper for the successful retry.

Call graph: calls 9 internal fn (accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, respond_with_status); 4 external calls (new, bind, new, assert_eq!).

async fn remote_control_start_allows_remote_control_invalid_url_when_disabled()

Purpose: Checks that startup does not reject an invalid or non-local remote-control URL when remote control remains disabled. This lets the app start even if a configured URL would only matter after enabling.

Data flow: The test starts remote control in persisted-resolution mode with no state database and an internal-looking URL, expects startup to succeed, then cancels and waits for the task to stop.

Call relations: The test runner calls it. It uses fake auth and the public start function, but intentionally does not create a listener because disabled startup should not make network contact.

Call graph: calls 1 internal fn (remote_control_auth_manager); 3 external calls (new, from_secs, timeout).

async fn remote_control_start_allows_missing_auth_when_enabled()

Purpose: Verifies that remote control can start its background task before ChatGPT auth exists, but waits instead of connecting. This supports signing in after the app has already launched.

Data flow: The test creates an AuthManager with no saved credentials, starts remote control in enabled mode, waits briefly to confirm the fake backend receives no connection, then shuts the task down.

Call relations: The test runner calls it. It uses a local listener and state runtime but no fake auth helper, because the missing-auth condition is the behavior under test.

Call graph: calls 4 internal fn (remote_control_state_runtime, remote_control_url_for_listener, default, shared); 6 external calls (new, from_millis, from_secs, bind, new, timeout).

async fn remote_control_start_reports_missing_state_db_as_disabled_when_enabled()

Purpose: Checks that remote control reports itself disabled when enabled startup is requested but no SQLite-backed state database is available. This avoids a half-enabled feature that cannot safely store enrollment.

Data flow: The test starts remote control without state storage, checks the initial disabled status notification, confirms no backend connection occurs, tries and fails to enable ephemerally, and checks the status does not change.

Call relations: The test runner invokes it. It uses the listener URL helper and fake auth, then exercises both startup status and the handle’s enable path.

Call graph: calls 2 internal fn (remote_control_auth_manager, remote_control_url_for_listener); 6 external calls (new, from_millis, from_secs, bind, assert_eq!, timeout).

async fn remote_control_handle_enable_disable_stops_and_restarts_connections()

Purpose: Tests that disabling remote control closes the active WebSocket and prevents reconnect, and enabling it again restarts connection attempts. This protects the user’s on/off control.

Data flow: The test starts remote control, completes enrollment and WebSocket connection, calls disable through the handle, verifies disabled status and socket closure, then calls enable and verifies a new connection is made.

Call relations: The test runner calls it. It combines the public handle methods with fake backend helpers and status watchers to prove state changes affect the live network task.

Call graph: calls 10 internal fn (accept_http_request, accept_remote_control_connection, expect_remote_control_status, expect_remote_control_status_snapshot, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, test_server_name); 7 external calls (new, from_millis, from_secs, bind, new, assert_eq!, timeout).

async fn remote_control_transport_clears_outgoing_buffer_when_backend_acks()

Purpose: Checks that once the backend acknowledges an outgoing message, that message is not replayed after reconnect. This prevents users from receiving stale duplicate server messages.

Data flow: The test opens a virtual client, sends a server notification, captures its stream id, sends an acknowledgement from the fake backend, closes the client and WebSocket, reconnects, then verifies only a fresh ping response appears.

Call relations: The test runner invokes it. It uses the server-event reader with stream id so it can send the matching Ack envelope back through send_client_event.

Call graph: calls 11 internal fn (new, accept_http_request, accept_remote_control_connection, expect_remote_control_status, read_server_event_with_stream_id, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json (+1 more)); 13 external calls (new, from_secs, ConfigWarning, bind, new, Request, Integer, AppServerNotification, new, assert_eq! (+3 more)).

async fn remote_control_http_mode_enrolls_before_connecting()

Purpose: Tests the normal HTTP-mode startup path: enroll first, then connect the WebSocket using the server token and metadata returned by enrollment.

Data flow: The test starts remote control, captures the enrollment POST and verifies headers and JSON body, returns a token response, captures the WebSocket handshake headers, then sends client messages and checks outgoing server messages over the socket.

Call relations: The test runner calls it as a complete happy-path scenario. It uses nearly all core helpers: listener URL creation, fake auth and state, HTTP capture, JSON response, backend WebSocket capture, status waiting, client-event sending, and server-event reading.

Call graph: calls 10 internal fn (new, accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, send_client_event); 15 external calls (new, from_secs, ConfigWarning, bind, new, Request, Integer, AppServerNotification, Response, new (+5 more)).

async fn remote_control_http_mode_refreshes_persisted_enrollment_before_connecting()

Purpose: Verifies that when a saved enrollment already exists, remote control refreshes it instead of enrolling from scratch before connecting. This preserves the server identity across runs.

Data flow: The test saves a persisted enrollment, starts remote control, captures a refresh POST containing the saved server id and installation id, returns a refreshed token, then checks the WebSocket uses the same server id and new token.

Call relations: The test runner calls it. It uses the enrollment persistence functions to set up and later verify saved state, plus the fake backend helpers to drive refresh and connection.

Call graph: calls 9 internal fn (update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, remote_control_auth_manager_with_home, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json); 4 external calls (new, bind, new, assert_eq!).

async fn remote_control_stdio_mode_waits_for_client_name_before_connecting()

Purpose: Checks that in stdio-style startup, remote control waits for the app-server client name before looking up and refreshing an enrollment. This avoids using the wrong saved record.

Data flow: The test saves an enrollment tied to a client name, starts remote control with a one-shot channel for that name, confirms no backend request happens before the name arrives, sends the name, then verifies refresh and WebSocket connection use the saved server id.

Call relations: The test runner invokes it. It combines the one-shot client-name channel with persisted enrollment setup and fake backend capture to test the waiting behavior.

Call graph: calls 9 internal fn (update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, remote_control_auth_manager_with_home, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json); 6 external calls (new, from_millis, bind, new, assert_eq!, timeout).

async fn remote_control_waits_for_account_id_before_enrolling()

Purpose: Tests that remote control waits for an account id before enrolling with the backend. Auth without an account id is not enough, because enrollment records are scoped to an account.

Data flow: The test saves auth without an account id, starts remote control, confirms no request is made, then saves auth with an account id and reloads the auth manager. It then observes enrollment and WebSocket connection using the expected server id.

Call relations: The test runner calls it. It uses remote_control_auth_dot_json to switch auth file contents and relies on AuthManager reload to wake the remote-control task before its normal retry delay.

Call graph: calls 10 internal fn (normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, remote_control_auth_dot_json, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, default, shared); 8 external calls (new, from_millis, bind, new, assert_eq!, save_auth, gethostname, timeout).

async fn persisted_enable_does_not_follow_auth_to_an_account_without_a_preference()

Purpose: Verifies that a saved enable preference for one account does not automatically enable remote control for another account. This keeps per-account privacy choices separate.

Data flow: The test saves auth and an enabled enrollment for account A, starts remote control and connects, then switches auth to account B and closes the socket. It waits for desired state to become disabled and checks no account B enrollment was created.

Call relations: The test runner invokes it. It uses auth-file generation, persisted enrollment setup, backend refresh/connection helpers, and a desired-state receiver from the remote-control handle.

Call graph: calls 11 internal fn (update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, remote_control_auth_dot_json, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, default (+1 more)); 8 external calls (new, from_millis, from_secs, bind, new, assert_eq!, save_auth, timeout).

async fn remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment()

Purpose: Checks that if refreshing a saved enrollment returns 404, remote control treats the saved server as stale and enrolls again. This lets recovery happen when the backend no longer knows the old server id.

Data flow: The test saves a stale enabled enrollment, starts remote control, observes a refresh request and a status tied to the stale environment, returns 404, then captures a new enroll request, returns a new server id, and verifies connection and saved state are updated.

Call relations: The test runner calls it. It uses persistence setup, status waiting, HTTP status responses, token JSON responses, and backend WebSocket capture to prove the fallback path.

Call graph: calls 11 internal fn (update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, remote_control_auth_manager_with_home, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json (+1 more)); 5 external calls (new, bind, new, assert_eq!, gethostname).

async fn remote_control_http_mode_reenrolls_after_explicit_missing_server_404()

Purpose: Tests a second stale-enrollment path: refresh succeeds, but the WebSocket upgrade returns a 404 body saying the remote app server was not found. Remote control should then enroll again.

Data flow: The test saves a stale enrollment, refreshes it successfully, rejects the WebSocket request with a specific missing-server 404 response, then expects a new enrollment and a successful WebSocket connection using the refreshed server id.

Call relations: The test runner invokes it. It uses raw HTTP capture for the failed WebSocket upgrade and the normal backend WebSocket helper for the final successful connection.

Call graph: calls 11 internal fn (update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, remote_control_auth_manager_with_home, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json (+1 more)); 6 external calls (new, bind, new, assert_eq!, gethostname, json!).

async fn remote_control_http_mode_preserves_stale_enrollment_when_reenrollment_fails()

Purpose: Checks that a stale saved enrollment is not erased if attempted re-enrollment fails. This avoids losing the last known server identity during temporary backend failures.

Data flow: The test saves a stale enrollment, makes refresh return 404, makes re-enroll return 500, allows a retry refresh to also fail, then checks both in-memory current enrollment and persisted state still contain the stale record.

Call relations: The test runner calls it. It uses status-code response helpers instead of successful WebSocket helpers because the test focuses on failure preservation.

Call graph: calls 8 internal fn (update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, remote_control_auth_manager_with_home, remote_control_state_runtime, remote_control_url_for_listener, respond_with_status, test_server_name); 4 external calls (new, bind, new, assert_eq!).

async fn remote_control_http_mode_preserves_enrollment_after_generic_websocket_404()

Purpose: Verifies that not every WebSocket 404 means the saved enrollment is stale. A generic 404 response should preserve the enrollment and allow later retry with the same server id.

Data flow: The test saves an enrollment, refreshes it successfully, rejects the first WebSocket upgrade with a generic 404 and extra headers, confirms the persisted enrollment remains, then accepts a later WebSocket connection using the same server id and token.

Call relations: The test runner invokes it. It uses the custom status-with-headers responder to simulate an ordinary infrastructure 404, then status snapshot waiting to confirm eventual connection.

Call graph: calls 13 internal fn (update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, expect_remote_control_status_snapshot, remote_control_auth_manager_with_home, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener (+3 more)); 4 external calls (new, bind, new, assert_eq!).

async fn accept_remote_control_connection(listener: &TcpListener) -> WebSocketStream<TcpStream>

Purpose: Accepts a WebSocket connection from the remote-control code without inspecting the handshake details. Tests use it when they only need an open socket.

Data flow: It receives a TCP listener, waits up to five seconds for an incoming TCP connection, performs a WebSocket handshake, and returns the WebSocket stream.

Call relations: Routing and enable/disable tests call this after enrollment has completed. It hands them a WebSocket stream they can use with send_client_event and read_server_event helpers.

Call graph: called by 3 (remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages); 4 external calls (from_secs, accept, timeout, accept_async).

async fn accept_http_request(listener: &TcpListener) -> CapturedHttpRequest

Purpose: Accepts and parses a single plain HTTP request from the remote-control code. It lets tests inspect request lines, headers, and bodies without running a full web server.

Data flow: It receives a TCP listener, waits for a connection, reads the request line, reads headers into a lowercase map, reads the body based on content-length, and returns a CapturedHttpRequest containing the original stream for responding.

Call relations: Most enrollment, refresh, and failed-WebSocket tests call this. They inspect the captured request and then pass its stream to response helpers.

Call graph: called by 14 (persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, 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, remote_control_stdio_mode_waits_for_client_name_before_connecting, remote_control_transport_clears_outgoing_buffer_when_backend_acks (+4 more)); 8 external calls (new, new, from_secs, from_utf8, new, accept, timeout, vec!).

async fn respond_with_json(mut stream: TcpStream, body: serde_json::Value)

Purpose: Writes a simple successful HTTP JSON response to a captured test connection. It is the fake backend’s normal success reply.

Data flow: It receives a TCP stream and JSON body, serializes the JSON to text, builds a 200 OK response with content type and length, writes it to the stream, and flushes it.

Call relations: Tests call this after accept_http_request captures enrollment or refresh requests. It supplies the production remote-control code with the server token data it expects.

Call graph: called by 13 (persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, 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, remote_control_stdio_mode_waits_for_client_name_before_connecting, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages (+3 more)); 4 external calls (flush, write_all, to_string, format!).

async fn respond_with_status(stream: TcpStream, status: &str, body: &str)

Purpose: Writes an HTTP response with a chosen status and body but no extra headers. Tests use it to simulate backend failures such as 401, 404, or 500.

Data flow: It receives a stream, status text, and body text, then delegates to respond_with_status_and_headers with an empty header list.

Call relations: Failure-path tests call this when they only care about the status code and body. The actual response formatting is handed off to the more general status-and-headers helper.

Call graph: calls 1 internal fn (respond_with_status_and_headers); called by 4 (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_transport_refreshes_server_token_after_websocket_unauthorized).

async fn respond_with_status_and_headers(
    mut stream: TcpStream,
    status: &str,
    headers: &[(&str, &str)],
    body: &str,
)

Purpose: Writes an HTTP response with a chosen status, optional extra headers, and body. It supports tests that need to mimic more specific backend or proxy responses.

Data flow: It receives a stream, status line, extra header pairs, and body text, formats them into a complete HTTP response with content length, writes it, and flushes it.

Call relations: respond_with_status uses this for simple failures, and the generic-WebSocket-404 test calls it directly when extra diagnostic headers matter.

Call graph: called by 2 (remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, respond_with_status); 3 external calls (flush, write_all, format!).

async fn accept_remote_control_backend_connection(
    listener: &TcpListener,
) -> (CapturedWebSocketRequest, WebSocketStream<TcpStream>)

Purpose: Accepts a WebSocket connection and records the request path and headers used during the handshake. Tests use it when they must verify auth tokens, server ids, installation ids, or protocol headers.

Data flow: It waits for a TCP connection, performs a WebSocket handshake with a callback that copies the request path and headers, then returns both the captured request data and the WebSocket stream.

Call relations: Enrollment, refresh, reconnect, and stale-enrollment tests call this after the fake backend has replied to HTTP setup requests. It gives them both an open socket and evidence that the connection was made correctly.

Call graph: called by 10 (persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_http_mode_enrolls_before_connecting, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, 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, remote_control_stdio_mode_waits_for_client_name_before_connecting, remote_control_transport_reconnects_after_disconnect, remote_control_transport_refreshes_server_token_after_websocket_unauthorized, remote_control_waits_for_account_id_before_enrolling); 6 external calls (new, from_secs, accept, new, timeout, accept_hdr_async).

async fn send_client_event(
    websocket: &mut WebSocketStream<TcpStream>,
    client_envelope: ClientEnvelope,
)

Purpose: Sends a remote-control client envelope over the fake backend WebSocket. Tests use it to imitate a remote client pinging, initializing, sending JSON-RPC, acknowledging messages, or closing.

Data flow: It receives a mutable WebSocket stream and a ClientEnvelope, serializes the envelope to JSON text, sends it as a WebSocket text frame, and produces no returned value.

Call relations: Routing, reconnect, buffer-ack, and HTTP-mode tests call this after accepting a WebSocket. The remote-control transport reads these frames as if they came from the real backend.

Call graph: called by 4 (remote_control_http_mode_enrolls_before_connecting, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages, remote_control_transport_reconnects_after_disconnect); 3 external calls (send, to_string, Text).

async fn read_server_event(websocket: &mut WebSocketStream<TcpStream>) -> serde_json::Value

Purpose: Reads the next server event from the fake backend WebSocket and returns only its JSON content. It hides the stream id when the test does not need it.

Data flow: It receives a WebSocket stream, calls read_server_event_with_stream_id, discards the returned stream id, and returns the JSON event.

Call relations: Tests use this for straightforward assertions about pong and server-message events. It delegates all frame reading and ping handling to the stream-id-aware helper.

Call graph: calls 1 internal fn (read_server_event_with_stream_id).

async fn read_server_event_with_stream_id(
    websocket: &mut WebSocketStream<TcpStream>,
) -> (serde_json::Value, StreamId)

Purpose: Reads the next text event sent by the app server over WebSocket and also extracts its stream id. The stream id is needed when tests must send an acknowledgement for that exact outgoing message stream.

Data flow: It receives a mutable WebSocket stream, loops until a text frame arrives, replies to WebSocket pings with pongs, ignores pongs, fails on unexpected close or binary frames, parses the text as JSON, removes the stream_id field, and returns the remaining event plus the stream id.

Call relations: read_server_event calls this for simpler cases, and the outgoing-buffer acknowledgement test calls it directly so it can acknowledge the exact stream used by the server message.

Call graph: called by 2 (read_server_event, remote_control_transport_clears_outgoing_buffer_when_backend_acks); 8 external calls (from_secs, next, send, new, panic!, from_str, timeout, Pong).

async fn pipes_stdin_and_stdout_through_socket() -> anyhow::Result<()>

Purpose: This test proves that codex-stdio-to-uds works as a two-way pipe between normal process input/output and a local Unix socket. It is used to catch regressions where the command stops sending stdin to the socket, stops returning the socket reply on stdout, exits with an error, or hangs.

Data flow: The test starts with a temporary directory, a socket path, and the bytes request. It writes request to a file so that file can become the child program’s stdin. It then starts a local socket listener and, in the background, waits for a connection, reads the expected request bytes, and writes back response. In parallel, it launches the real codex-stdio-to-uds binary pointed at that socket. The child receives the file contents as stdin and should print the socket reply to stdout. The test collects the child’s exit status, stdout, stderr, and the fake server’s progress messages. The final result is success only if the child exited cleanly, stdout equals response, and the server received exactly request.

Call relations: This function is the whole test scenario. It sets up the fake socket server, starts the real command-line program under test, waits for both sides to finish, and then checks the results. During setup it asks the socket library to bind to the temporary path, and during verification it uses assertions to compare the observed bytes with the expected bytes. If the child process does not finish in time, the test gathers the server’s progress messages and the child’s stderr so the failure tells a useful story instead of just timing out.

Call graph: calls 1 internal fn (bind); 11 external calls (Ok, assert!, assert_eq!, eprintln!, format!, channel, write, new, spawn, spawn_blocking (+1 more)).

fn danger_full_access_defaults_to_no_sandbox_without_network_requirements()

Purpose: This test confirms that when file access is fully open and there are no managed network needs, the sandbox manager does not add a sandbox. That avoids unnecessary wrapping when there is nothing to restrict.

Data flow: It creates a new sandbox manager, gives it an unrestricted file policy, enabled network policy, automatic sandbox preference, disabled Windows sandboxing, and says there are no managed network requirements. The manager returns its initial sandbox choice, and the test expects that choice to be no sandbox at all.

Call relations: This test directly exercises the manager’s initial sandbox selection path. It uses the unrestricted policy constructor and then compares the manager’s answer with the expected safe default.

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