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

Relationships

#4918 A serve host registers the workspaces it runs in the workspace registry, where they are

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

Second of six steps that merge a serve host's workspaces into the workspace registry. swamp-club#4865 lists the whole sequence. One PR. Depends on swamp-club#4848 (workspace services), which has landed.

Problem

A serve host knows its workspaces from the folders in <host folder>/workspaces/. The workspace registry (<config dir>/workspaces.json) is a second list that the host never touches. swamp-club#4919 and swamp-club#4865 make the registry the host's only list. Before that can happen, every workspace a host already runs has to be in the registry, or an upgrade would stop serving it.

Change

Every workspace a host runs is also a registry entry. The host writes the registry and does not read it to decide anything: the folder scan still decides what is served, so nothing a client sees changes.

The host registers what it runs

  • At startup and with each rescan, the host registers every workspace folder in workspaces/ that the registry lacks. The entry's name is the folder's name and its folder is the folder's real path. Nothing is moved or copied.
  • The entry is recorded as swamp workspace import would record it, with no trust mark.
  • workspace.create registers the workspace it made, after the folder is renamed into place. A create stopped before that is registered by the host's next rescan.
  • A delete removes the entry: after the folder is removed and before the wanted file, which is still removed last. A host stopped halfway finishes at its next start, as it does today.
  • A folder removed by hand loses its entry once its serve has stopped, when its status file is removed. The name is free again, as it is today.
  • The host removes only an entry whose folder is inside its own workspaces/ and whose name is that folder's name.

Writes follow the registry's own rules

  • Every write goes through the workspace store, under the registry's lock. A registry the host creates adopts the repos under the data dir first, as any command that writes does. Otherwise a later workspace command would find a registry and never adopt them.
  • The host waits for the lock for a bounded time. A write that fails or times out is tried again at the next rescan and logged once per reason. It never delays or stops a serve.
  • The file gains no field and no schema version. An older swamp reads and rewrites it without loss.

A folder that cannot be registered

  • The name is registered to another folder, or the folder is registered under another name. The host does not change the registry.
  • It logs an error once per reason. The error names both folders, says that a later release will stop serving this folder until the clash is resolved, and names swamp workspace remove.
  • The workspace keeps running, as it does today.

A registry that cannot be read

  • The file is corrupt, or was written by a newer swamp. The host logs it, registers nothing and goes on serving. The repository already refuses to rewrite such a file.

Compatibility

  • swamp serve host, host.yaml, the wanted and status files and every address are unchanged.
  • What is new is visible only on the host's machine: its workspaces appear in swamp workspace list and on the swamp start page.
  • swamp workspace remove on one of these entries has no lasting effect while the folder is in workspaces/: the next rescan registers it again. The design doc says so.

Decisions this issue makes

  • Where the write runs. The expected answer is that the root registers on create, so swamp workspace list is right at once, and the host's rescan is the safety net.
  • How long the host waits for the registry's lock. Long enough to pass a workspace command, short enough that a rescan is never held up.

Done when

  • A host started on a host folder that already holds two workspaces lists both in swamp workspace list, each at its own folder. Both still run and answer at their addresses. Their wanted and status files are unchanged.
  • swamp serve workspace create adds an entry. swamp serve workspace rm removes the folder and the entry.
  • A folder removed by hand loses its entry after its serve stops.
  • A clash is logged once, the registry is unchanged and the workspace is still served.
  • With a registry that cannot be read, the host serves as before and writes nothing.
  • A registry the host created holds the repos under the data dir that a first read would adopt.
  • The JSON the host writes has only the keys the registry has today.
  • The tests use a fake process port and a registry in a temp config folder supplied with withMockedEnv. They spawn no processes.
  • The fitness rule for src/serve/host/ still passes.

Where to look

  • src/serve/host/serve_host.ts, src/serve/host/workspace_folder.ts and src/serve/host/workspace_reconciler.ts for the scan and the removal steps.
  • src/libswamp/hosted_workspace/create.ts for create.
  • src/libswamp/workspace/workspace_store.ts (loadWorkspaceRegistry, importWorkspace) and src/infrastructure/persistence/workspace_registry_file_repository.ts for the registry. A name src/serve/ imports from libswamp must be exported from src/libswamp/mod.ts.
  • design/surfaces/workspace.md for the registry's own rules.

Out of scope

  • Reading the registry to decide what the host serves. That is swamp-club#4919.
  • Workspaces registered outside workspaces/. The host still ignores them.
  • Moving any folder or file.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 14 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/19/2026, 11:40:31 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/19/2026, 9:29:36 PM

Sign in to post a ripple.