What the agent does
The agent starts from how the server stops today. In a Tokio server laid out like tokio-rs/mini-redis, src/bin/server.rs binds a TcpListener and calls server::run(listener, signal::ctrl_c()), so the only signal the process ever reacts to is SIGINT. src/server.rs already has the drain machinery: run holds a broadcast::Sender called notify_shutdown and an mpsc::Sender called shutdown_complete_tx, each accepted connection gets a Shutdown wrapper from src/shutdown.rs around a subscribed receiver plus a clone of the completion sender, and after the select! between server.run() and the shutdown future it drops both senders and waits on shutdown_complete_rx.recv() until every handler task has dropped its clone. What is missing is SIGTERM, which is what docker stop, Kubernetes and systemd send, and a limit on how long that final wait may take.
It adds the signal first. Cargo.toml enables tokio with features = ["full"], so tokio::signal::unix::signal(SignalKind::terminate()) is available with no new dependency. The agent writes a shutdown_signal future in src/bin/server.rs that completes on either ctrl_c() or the SIGTERM stream and passes it to server::run in place of signal::ctrl_c(). The CI matrix in .github/workflows/ci.yml builds on windows-latest as well as Ubuntu and macOS, so the SIGTERM branch is behind #[cfg(unix)] with a ctrl_c-only future on other targets, and the binary keeps compiling on all three.
Then it bounds the drain. A handler in Handler::run returns as soon as self.shutdown.recv() fires between frames, but a client that has sent half a frame, or a subscriber parked in SUBSCRIBE that never sends another, keeps its task alive and shutdown_complete_rx.recv() waiting for it. The agent wraps that final wait in tokio::time::timeout with a duration run takes as a parameter, logs shutdown timed out with the number of connections still open through the tracing macros the file already uses, and returns so the process exits; the Semaphore permit and the Connection buffers drop with the task. MAX_CONNECTIONS and the new deadline become one small Config passed to run, since both are hard-coded constants the comment in server.rs already says a real application would make configurable.
The proof is a test in tests/server.rs, next to the existing start_server helper that spawns server::run with ctrl_c() on a port bound to 127.0.0.1:0. The new test passes a oneshot receiver as the shutdown future instead, opens a client that has sent *2\r\n$3\r\nGET\r\n and nothing more, fires the oneshot, and asserts that run returns within the deadline rather than hanging; a second test opens a connection, completes a SET, fires shutdown and asserts the server returns promptly with no timeout logged. It runs cargo test, cargo test --features otel and cargo fmt --all --check, the three commands ci.yml runs, and opens the pull request with their output.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add graceful shutdown on SIGTERM to this Tokio server. Read Cargo.toml, src/bin/server.rs, src/server.rs, src/shutdown.rs, src/connection.rs, tests/server.rs and .github/workflows/ci.yml first. In src/bin/server.rs write a shutdown_signal future that completes on ctrl_c or on SIGTERM (tokio::signal::unix, behind cfg(unix) because CI builds on Windows) and pass it to server::run. In src/server.rs bound the final wait on shutdown_complete_rx with tokio::time::timeout using a drain deadline passed into run alongside the connection limit; log a warning naming how many connections were still open when the deadline passed. Add tests in tests/server.rs: one where a client has sent a partial frame and run returns within the deadline, one where an idle connection lets run return promptly. Run cargo test, cargo test --features otel and cargo fmt --all --check, and open a pull request with the output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that changes src/bin/server.rs, src/server.rs and tests/server.rs, with no new crate in Cargo.toml. The description shows the signal future, the timeout around the drain and the new run signature, and quotes the cargo test output for both features and the cargo fmt check.
The run's record keeps each command and its output, so a reviewer sees the partial-frame test pass against the deadline rather than reads that it does, and sees the Windows path compile under the cfg split.
Before merging, a reviewer picks the deadline. A container runtime gives a process a fixed grace period before SIGKILL, and the drain deadline has to be shorter than it, so the pull request names the default it chose and where to change it, and the reviewer sets it against their own stop_grace_period or terminationGracePeriodSeconds.
Run it on every Linear issue labelled agent
Shutdown bugs arrive as issues: a deploy that waits for SIGKILL, a client whose last command was lost on restart. With Linear connected under Settings → Connections in the console, add an automation to the Project with a linear trigger on linear.issue.labeled and the label agent. Its saved prompt asks for what this one asks for: read the entry point and the server module, handle SIGTERM, bound the drain, add the tests and open a pull request. The trigger adds the issue after the prompt and fills in no placeholder, so the grace period the operator needs comes from the issue text.
The trigger fires only when someone in your Rush org adds the label, and a change made by an app integration never fires it. A burst of labels is held to the automation's max_runs_per_hour. A team with several Tokio services sends this body once per repository from its own server instead, each with its repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
A shutdown bug only shows under a signal, and reproducing it means a server, a client stuck mid-frame and a timer, all at once. The agent runs that experiment in its own sandbox: it starts the binary, sends a half frame with the client it wrote, sends SIGTERM and watches whether the process exits, and the record keeps every command and its output. On a laptop that experiment is a one-off nobody writes down; here it is the evidence attached to the pull request.
The change is small and easy to review, which is why it is worth running on every service rather than one. Each repository gets its own sandbox, its own cargo test run and its own pull request, at once, and a reviewer reads a diff of about three files per service with the test output beside it.
Frequently asked questions
Does this change the drain logic that already exists?
No. The broadcast channel, the Shutdown wrapper and the completion channel stay as they are. The change adds a second signal that triggers them and a deadline on the wait at the end, so a connection that never reaches a safe point cannot hold the process open.
What happens to a command that is mid-flight when SIGTERM arrives?
It finishes. The handler checks for shutdown only between frames, so a SET that has been fully read is applied and its reply written before the task returns. A connection that has sent part of a frame and stopped is the one the deadline covers, since its read never completes.
Why keep SIGINT at all?
Because cargo run in a terminal and Ctrl-C send SIGINT, and the tutorial server has always stopped on it. The future the agent writes completes on either signal, so local use does not change and the container case is added.
Will the Windows build still pass?
Yes. tokio::signal::unix does not exist on Windows, and CI builds there, so the SIGTERM branch is compiled only on Unix targets and the Windows build keeps the ctrl_c future alone. The agent runs the test suite under the same commands the workflow runs.