Relationships
#4803 ManagedServe: the entity that decides when a hosted serve starts, restarts and gives up
Opened by zack · 11/16/2026· Shipped 11/16/2026
Issue 4 of 18 in the execution plan of design/surfaces/serve-workspaces.md. One PR. No dependencies.
Problem
swamp serve host will run one swamp serve child per workspace and has to decide, for each child, when to start it, when to restart it and when to give up. Those rules are the part of the supervisor most likely to be wrong, and the part hardest to test once it is mixed with process handling.
Change
Add the ManagedServe entity in src/domain/serve/. It holds the wanted state, the observed state, the crash count and the backoff for one child.
Its step is pure. From one event and the current time it returns the next state and one action: spawn, stop or wait. It does no I/O and reads no clock.
Observed states are stopped, starting, ready, backoff and failed.
The rules:
startingbecomesreadyon a ready event. The supervisor raises that event when the child's/readyreturns 200. A listening port is not enough, since serve listens before it is ready.- Exit 75 means a restart is safe, as after a lost writer lease. The child is started again after a short backoff and the exit never counts as a crash.
- Any other exit the host did not ask for is a crash. Backoff is exponential and capped.
- Repeated crashes inside a window hold the child in
faileduntil someone resumes the workspace. - A wanted state of suspended or deleted leads to a stop action and then
stopped.
Done when
- Unit tests cover each rule above.
- A property test (
*_property_test.ts, fast-check) runs random event sequences and checks that:- the backoff never passes its cap
- exit 75 never raises the crash count
failedis left only by a resume
- Nothing in the entity spawns a process, opens a socket or reads the clock.
Out of scope
Spawning, reading the listening line, polling /ready and signals. Those are the supervisor, the next issue in the plan.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.