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

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 --json in the child's repo folder with the flags the host adds: --host 127.0.0.1, --port 0, --address with the child's public address, --trusted-hosts with the host's public name, --trust-proxy and --exit-on-stdin-close. The child's environment is set explicitly.
  • Read the port. The child reports the port it got on its --json listening 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-close then 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.Command adapter 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, watching workspaces/ and the listener. Those are swamp serve host, issue 7 in the plan.
  • Wanted and status files. Issue 8 in the plan.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 8 MOREREVIEW+ 26 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/17/2026, 12:11:46 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/16/2026, 7:31:50 PM

Sign in to post a ripple.