Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneeszack

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:

  • starting becomes ready on a ready event. The supervisor raises that event when the child's /ready returns 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 failed until 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
    • failed is 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.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 8 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/16/2026, 7:22:46 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/16/2026, 6:34:56 PM

Sign in to post a ripple.