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

Relationships

#4867 Default off: the serve host starts a workspace's serve only when its wanted file says active

Opened by zack · 11/18/2026· Shipped 11/18/2026

Issue 20 of the execution plan in design/surfaces/serve-workspaces.md. One PR. Depends on swamp-club#4836 (wanted and status files), merged.

Problem

The serve host starts a serve for every folder it finds in workspaces/. A folder with no wanted file counts as active, and so does one whose wanted file cannot be read when the host has read none. An operator cannot have a workspace on the host that is not running without suspending it afterwards.

Removing a wanted file also starts a workspace. A suspended workspace whose wanted file is deleted is started at the next rescan, because an absent file reads as active (src/serve/host/workspace_reconciler.ts).

Change

The design's Default off rule, under The host: the host never starts a serve for a workspace on its own. It starts one only when the workspace's wanted file says active.

  • A folder with no wanted file is listed and not started. It gets a status file that says it is stopped, and its address answers as a stopped workspace's does.
  • A wanted file that cannot be read starts nothing. The problem is logged and put in the status file, as today.
  • active starts the serve. A resume writes it, or an operator editing the file. The choice is in the file, so the workspace comes back after a host restart.
  • A running workspace is stopped only by suspended or deleted. A wanted file that cannot be read does not stop it. A wanted file that is absent for one scan, as while an editor saves by removing and recreating it, does not stop it either.
  • The root still starts with the host. Naming it in host.yaml is the operator turning it on. It has no wanted file.
  • The host says what it did not start. One log line for each workspace it lists and does not start, naming the workspace and how to start it. With --json the workspaces line already carries each state.

Decisions this issue makes

The design leaves these to the PR. The PR states what it chose and updates the design doc.

  • A wanted file that stays absent while the workspace runs. The design says only that one scan's absence stops nothing. The expected answer is one rule for absent and unreadable alike: the workspace keeps the last state the host read whole, and when the host has read none it is not started. A running workspace whose wanted file is removed then keeps running until a wanted file says otherwise, and is not started again after a host restart.
  • What the status file's wanted field says for a workspace with no wanted file.

Upgrade

This changes what an existing host does. A workspace an operator made by hand, with no wanted file, has a serve today and will have none after the upgrade until its wanted file says active. The PR description says so, and the host's log line names the file to write.

Done when

  • A folder added to workspaces/ by hand has no serve until its wanted file says active.
  • A workspace resumed before a host restart has a serve after it. One that was never resumed has none.
  • A folder whose wanted file cannot be read, with none read before, has no serve.
  • Replacing a running workspace's wanted file, by removing and recreating it, does not stop it.
  • A running workspace whose wanted file becomes unreadable keeps running, and the status file carries the reason.
  • Removing a suspended workspace's wanted file does not start it.
  • The root starts with the host and has no wanted file.
  • The reconciler's tests use the fake supervisor and spawn no processes.
  • The design doc is updated: the Default off paragraph drops its not-yet-built sentence, the Lifecycle bullets that say a missing wanted file means active say what is now true, and last-verified names the commit.

Where to look

  • src/serve/host/workspace_reconciler.ts. step turns a missing record into running, and an absent read clears the record the host held.
  • src/domain/serve/hosted_workspace.ts for the wanted states and the mapping to the supervisor's.
  • src/serve/host/supervisor.ts. A workspace already suspended when the host starts is added and never started today, which is the state a new folder now gets.

Out of scope

  • workspace.create writing its wanted file as suspended. swamp-club#4848 does that, and it is correct before and after this change.
  • Workspaces from the workspace registry. swamp-club#4865.
  • A setting in host.yaml that turns default off back on. The design has none.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 8 MOREREVIEW+ 6 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/18/2026, 4:56:28 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/18/2026, 3:15:54 PM

Sign in to post a ripple.