refactor(server): drop Rc; borrow handler from async state

The driver's async fn owns `handler: H` as a local. Per-client
futures borrow `&handler` from the same async state — Rust's
async-fn state machine makes the self-borrow sound (state is
pinned, never moves). When drain completes, the outer async
returns `handler` by move.

Removes the internal `Rc<H>` + `Rc::try_unwrap` path (and the
related panic doc).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: wan9chi

crates/vite_task_server/src/lib.rs

@@ -1,7 +1,6 @@
 use std::{
     ffi::{OsStr, OsString},
     io,
-    rc::Rc,
     sync::Arc,
 };
 
@@ -59,24 +58,14 @@ impl StopAccepting {
 ///
 /// Returns an error if creating the listener fails (on Unix, this includes
 /// creating the temp socket path).
-///
-/// # Panics
-///
-/// The driver future panics if, after drain, the handler still has other
-/// `Rc` references — which would indicate a logic bug in the server
-/// (per-client futures should all have dropped their clones by then).
 pub fn serve<'h, H: Handler + 'h>(handler: H) -> io::Result<(OsString, ServerHandle<'h, H>)> {
-    let handler_rc = Rc::new(handler);
     let stop_token = CancellationToken::new();
     let (name, bound) = bind_listener()?;
 
-    let run_handler = Rc::clone(&handler_rc);
     let run_stop = stop_token.clone();
     let driver = async move {
-        run(bound, run_handler, run_stop).await;
-        Rc::try_unwrap(handler_rc)
-            .ok()
-            .expect("drain completed but handler still has other Rc references")
+        run(bound, &handler, run_stop).await;
+        handler
     }
     .boxed_local();
 
@@ -120,20 +109,18 @@ const fn listener_of(bound: &Bound) -> &Listener {
     bound
 }
 
-async fn run<H: Handler>(bound: Bound, handler: Rc<H>, shutdown: CancellationToken) {
+async fn run<H: Handler>(bound: Bound, handler: &H, shutdown: CancellationToken) {
     let mut clients = FuturesUnordered::new();
 
-    // Accept phase: accept new clients until shutdown fires. Each per-client
-    // future gets its own `Rc<H>` clone; when they all complete the last
-    // clone drops inside this scope along with `handler`.
+    // Accept phase: accept new clients until shutdown fires.
     loop {
         let listener = listener_of(&bound);
         tokio::select! {
             () = shutdown.cancelled() => break,
             accept_result = listener.accept() => {
                 match accept_result {
                     Ok(stream) => {
-                        clients.push(handle_client(stream, Rc::clone(&handler)).boxed_local());
+                        clients.push(handle_client(stream, handler).boxed_local());
                     }
                     Err(err) => {
                         tracing::warn!(?err, "vite_task_server: accept failed");
@@ -147,16 +134,12 @@ async fn run<H: Handler>(bound: Bound, handler: Rc<H>, shutdown: CancellationTok
     // Stop accepting: drop the listener (and on Unix unlink the socket file).
     // Existing client streams continue to work.
     drop(bound);
-    // Drop our direct reference so only per-client futures hold clones.
-    drop(handler);
 
-    // Drain phase: wait for all in-flight per-client tasks to finish. Each
-    // ends when its client closes the stream (e.g., the task process exits
-    // and its sockets are closed by the OS).
+    // Drain phase: wait for all in-flight per-client tasks to finish.
     while clients.next().await.is_some() {}
 }
 
-async fn handle_client<H: Handler>(mut stream: Stream, handler: Rc<H>) {
+async fn handle_client<H: Handler>(mut stream: Stream, handler: &H) {
     let mut buf = Vec::new();
     loop {
         match read_frame(&mut stream, &mut buf).await {

docs/runner-task-ipc/server-design.md

@@ -8,7 +8,7 @@ The IPC server runs per spawn execution **only when fspy is enabled**, letting t
 
 1. **Server doesn't take a cancellation token.** The caller signals "stop accepting" via `StopAccepting::signal()`. The server has no awareness of external cancellation.
 2. **Handler is moved in, returned out.** The caller doesn't keep a reference. The driver owns the handler; on drain completion it returns it by value. No self-reference, no `&H` lifetime.
-3. **`Rc<H>` + `CancellationToken` internally** — both hidden from the public API.
+3. **`CancellationToken` is internal** — hidden from the public API (exposed only via `StopAccepting`).
 4. **Driver is `!Send`**, lifetime bounded by `H`'s lifetime — if `H: 'static`, the driver is `'static`; if `H` borrows, the driver respects that.
 
 ## Server API
@@ -43,7 +43,7 @@ The driver future, when polled:
 1. **Accept phase** — accepts new clients and pumps per-client futures (`FuturesUnordered`) until `StopAccepting::signal()` fires.
 2. **Listener teardown** — drops listener; Unix socket file auto-cleaned via `tempfile::NamedTempFile`.
 3. **Drain phase** — waits for in-flight per-client futures to complete naturally (each ends on client EOF).
-4. **Returns `H`** — via `Rc::try_unwrap` since all per-client clones have dropped.
+4. **Returns `H`** — the owned handler that was moved in at `serve()`.
 
 Dropping the driver before it resolves tears everything down immediately. Handler is dropped without being returned.
 
@@ -81,7 +81,7 @@ struct FspyState {
 **Not stored:**
 
 - `name` — consumed once to build envs, dropped immediately.
-- `handler` — lives inside `server.driver` via `Rc`; recovered by value when driver resolves.
+- `handler` — lives inside `server.driver`'s async state; recovered by value when the driver resolves.
 
 ### Driving the server during `pipe_stdio` / `child.wait`
 
@@ -121,11 +121,11 @@ The driver future _owns_ the handler (via `Rc<H>` internally). It doesn't need t
 
 If the caller wants to store `ServerHandle` in a struct without a lifetime parameter, they can use a `'static` handler (naturally satisfied by handlers that own all their state via `RefCell<...>` + cloned data).
 
-### Why `Rc<H>` internally instead of `&H`?
+### Handler is owned by the driver, not shared via `Rc`
 
-`&H` → per-client futures borrow from a single `H`. Storing both the handler and the driver in the same `FspyState` creates a self-reference.
+The driver's async function owns `handler: H` as a local. Per-client futures borrow `&handler` from that same async state; Rust's async-fn state machine makes this self-borrow sound (the state is pinned and never moves). All per-client futures live inside `FuturesUnordered` which is also part of the same state — borrow scopes are contained.
 
-`Rc<H>` → per-client futures share ownership. The driver captures `Rc<H>`, clones into each per-client future. When drain completes, `Rc::try_unwrap` succeeds because all per-client clones have dropped, and the driver returns the owned `H`.
+When drain completes and all per-client futures have been dropped, the outer async returns `handler` by move. No `Rc`, no `try_unwrap`, no panic possible.
 
 ### Why return `H` from the driver?