Relationships
#4805 The serve host supervisor: start, watch and stop one serve per workspace
Opened by zack · 11/16/2026· Shipped 11/17/2026
Issue 5 of 18 in the execution plan of design/surfaces/serve-workspaces.md. One PR. Depends on swamp-club#4797 (serve --exit-on-stdin-close) and swamp-club#4803 (ManagedServe).
Problem
ManagedServe decides what should happen to a hosted serve. Something has to carry those decisions out: start the process, learn its port, find out when it is ready, stop it, and feed what happened back in as events.
Change
Add the supervisor. It drives one ManagedServe per child through a process port.
The port is the only place that touches a process. It offers:
- Spawn. Start
swamp serve --jsonin the child's repo folder with the flags the host adds:--host 127.0.0.1,--port 0,--addresswith the child's public address,--trusted-hostswith the host's public name,--trust-proxyand--exit-on-stdin-close. The child's environment is set explicitly. - Read the port. The child reports the port it got on its
--jsonlistening line. - Poll
/ready. A 200 raises the ready event. Serve listens before it is ready, so a listening port is not enough. - Stop. SIGTERM, so serve's drain path runs.
- Hold stdin. The supervisor keeps each child's stdin open. A child started with
--exit-on-stdin-closethen never outlives the host, so the host needs no pid files and no orphan clean-up.
The supervisor turns what the port reports into ManagedServe events (listening, ready, exited with a code) and carries out the action each step returns: spawn, stop or wait. Stopping the supervisor stops every child through its drain path first.
The supervisor also answers the lookup the router takes: name to port and state.
Done when
- Tests drive the supervisor with a fake process port and cover: a child that starts and becomes ready, an exit 75 that restarts without counting as a crash, a crash that backs off, repeated crashes that end in
failed, a stop, and a shutdown that stops every child. - Waits in tests poll a condition with
waitFor. Backoff is tested by the work done, not by measured time. - The
Deno.Commandadapter for the port stays thin, since tests in this repo do not spawn processes. - Every promise the supervisor starts is awaited or handled, including the readers of each child's output.
Out of scope
- Reading
host.yaml, watchingworkspaces/and the listener. Those areswamp serve host, issue 7 in the plan. - Wanted and status files. Issue 8 in the plan.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.