Relationships
#4836 Wanted and status files: suspend, resume and delete a hosted workspace
Opened by zack · 11/17/2026· Shipped 11/17/2026
Issue 8 of 18 in the execution plan of design/surfaces/serve-workspaces.md. One PR. Depends on swamp-club#4835 (swamp serve host).
Problem
A host runs every workspace folder it finds. There is no way to stop one workspace and keep its data, no way to remove one safely while the host runs, and no place to read why a workspace is not ready.
The root workspace will take the lifecycle requests, but the root and the supervisor never call each other. They need a channel that works across two processes and survives a restart of either.
Change
Two small files per workspace, beside its folder in workspaces/:
- Wanted, written by the root:
active,suspendedordeleted, with the creator and the time. A folder without one isactive. - Status, written by the supervisor: the observed state, the restart count and the reason when it is not ready.
Add the HostedWorkspace aggregate and its file store. The aggregate holds the name, the creator and the wanted state, and the wanted file is its store. Writes are atomic, so a reader never sees half a file.
The host reads and watches the wanted files and passes each wanted state to the supervisor:
suspendedstops the workspace's serve and keeps everything.activestarts it again. This is also what resumes a workspace held infailed.deletedstops the serve, then removes the folder and both files. A host that stopped halfway finishes at its next start.
The supervisor writes a status file whenever a workspace's observed state changes.
An unreadable wanted file is reported in the host's log and in the status file. It does not stop or delete the workspace.
Done when
- An operator can suspend and resume a workspace by editing its wanted file while the host runs.
- A workspace marked
deletedis stopped and removed, and a delete interrupted between the stop and the removal completes at the next start. - The status file names the state, the restart count and the reason for a workspace that is not ready.
- A property test covers
HostedWorkspacestate changes, including thatdeletedis never left. - An integration test runs the host in-process on a temp folder with a fake process port and covers suspend, resume, delete and the interrupted delete.
Out of scope
- The services that write the wanted file for a request. Issue 10 in the plan.
workspace.*requests on the root. Issue 11 in the plan.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.