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

Relationships

#4865 Registered workspaces: a workspace registered anywhere on the machine is listed on the serve host and served in place on resume

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

Fourth of six steps that merge a serve host's workspaces into the workspace registry and make the host folder optional. One PR. Depends on swamp-club#4919 (the host takes its workspaces from the registry), and on swamp-club#4848 and swamp-club#4875, which have landed.

The sequence

Each step is one issue and one PR, leaves main working, and keeps an existing host folder running with no step by its operator.

  1. swamp-club#4917. Docs: the design keeps one list of workspaces, the registry, and a host needs no host folder.
  2. swamp-club#4918. A host registers every workspace it runs in the registry. The folder scan still decides what is served.
  3. swamp-club#4919. The host and the workspace services take their workspaces from the registry. Nothing an operator or a client sees changes.
  4. This issue. A workspace registered anywhere on the machine is listed on the host, and is served in place when resumed.
  5. swamp-club#4920. swamp serve host runs without a host folder.
  6. swamp-club#4921. A host with no host folder creates workspaces in the workspace location.

Problem

A serve host serves only repos inside its own workspaces/ folder, plus one root. A repo that already exists somewhere else on the machine cannot be served by the host without moving it.

Swamp already has a list of such repos: the workspace registry, which swamp workspace import and swamp workspace create add to. After swamp-club#4919 the host works from that registry, but passes over every entry outside workspaces/.

Change

The host lists every workspace in the registry of the user it runs as, starts none on its own, and serves one in place when it is resumed. The design section is Registered workspaces under The host.

Listed, not started

  • Every registered workspace is a workspace of the host, wherever its folder is. The host no longer passes over an entry outside workspaces/.
  • Each has a status file under its registry name, beside the wanted files in workspaces/. Its wanted file is there too.
  • Listing a workspace never starts a serve. One with no wanted file is stopped, and its address answers 503 with its state, like any stopped workspace.
  • workspace.list names every registered workspace, as it names every workspace today.
  • With no registry file and an empty workspaces/, the host lists nothing and creates no registry file.

Served in place

  • A wanted file that says active starts a serve in the registered folder, at /w/<name>. suspended stops it.
  • The child is started with the same flags and environment as any other workspace. The repo keeps its own datastore, vaults and serve.yaml. Nothing is copied into it.
  • The host admits it by the same rule as any child, including the refusal of auth mode none.

Whose a workspace is

  • A workspace whose folder is inside the host's workspaces/ is the host's own, as every workspace is today. Grants on workspace:<pattern> reach it and workspace.delete removes its folder and its registry entry. Nothing changes for these.
  • Any other registered workspace is the operator's own.
    • workspace.delete refuses it, for the root's admins too, and names swamp workspace remove.
    • Only the root's admins may suspend or resume it. The request handler refuses a grant holder who is not a root admin, even when a grant's pattern matches the name.
    • workspace.get follows the read grant, as today.
  • workspace.list and workspace.get say which kind a workspace is. The field is new and optional in the reply.
  • workspace.create refuses a registered name with already_exists.

A wanted file belongs to one folder

  • A wanted file is never applied to a folder other than the one it was written for. Otherwise a wanted file left behind by a removed workspace, or by a create that did not finish, would start a serve in whatever repo is imported under that name later.
  • The expected way: a wanted file can name its folder. One that names none stands for workspaces/<name>, which is what every wanted file means today. The host starts a serve only when the wanted file's folder is the entry's folder, and the status file's reason says when it is not.
  • suspend and resume write the folder for a workspace outside workspaces/, and leave it out for one inside. So the wanted files of an existing host folder do not change, and an older host still reads them.
  • An operator who resumes one of their own workspaces by hand names its folder in the wanted file. Editing the wanted line of an existing file works as before.
  • A name whose registered folder changes is stopped, and is not started in the new folder until its wanted file names it.

Leaving the registry

  • A workspace of the operator's own is stopped when it leaves the registry. Its wanted and status files are removed. Its folder is not touched.
  • A later import under the same name starts nothing.
  • An entry for a folder in workspaces/ cannot leave this way: the rescan registers before it reads.

Names and folders

  • A registered folder that is the root's repo is passed over, so no repo has two serves from one host.
  • A folder in workspaces/ whose name is registered to another folder is no longer served: the registry entry has the name, and is listed like any other. The host logs an error at every start that names both folders and swamp workspace remove. swamp-club#4918 has logged that clash since it landed.
  • A folder in workspaces/ that is not registered for any other reason is still served from its folder, as swamp-club#4919 leaves it.

Compatibility

  • Every workspace that ran before this change runs after it, at the same address, with no step by the operator, unless its name is registered to another folder (see Names and folders). Its repo, wanted file and status file stay where they are.
  • swamp serve host, --host-dir and host.yaml are unchanged.
  • The registry file gains no field and no schema version.
  • An older swamp serve workspace client must still list and get against this root, and must show the root's own message for the new refusal. The new field in the reply is optional.
  • One thing changes for an existing host: every repo its user has registered is now listed on it, stopped. None starts until a root admin resumes it.
  • Two hosts run by one user now share one list. Each lists every entry, and a name is unique across both. A second host needs its own SWAMP_HOME. The design doc's limits say so.

Decisions this issue makes

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

  • A registry that cannot be read at startup. swamp-club#4919 falls back to the folders in workspaces/. Here the fallback also covers the operator's own workspaces. The expected answer: the host serves what the wanted files name, each active one in the folder it names or stands for.
  • A wanted file that says deleted for a workspace of the operator's own. The delete service refuses, but an operator can still write the file by hand. The host must never remove or rename a folder outside its own workspaces/, whatever the wanted file says. The expected answer: the serve is stopped and the status file's reason says why nothing was removed.
  • The wanted file's new field. Its name, and whether it holds the real path. The schema is strict, so the field is optional and every wanted file written until now still parses.
  • The new refusal's code, and its place in the client's list of codes whose message the root wrote.

Done when

  • A host upgraded on an existing host folder serves every workspace it served before, at the same addresses.
  • A repo registered with swamp workspace import is listed as stopped while the host runs, within one rescan, and no serve was started for it. Its address answers 503.
  • A resume serves it at /w/<name> from its own folder, and a suspend stops it.
  • swamp workspace remove stops it and removes its wanted and status files. The folder is still there. An import under the same name starts nothing.
  • Removing the registry entry of a folder in workspaces/ changes nothing.
  • Delete refuses a workspace of the operator's own, for a root admin too. A grant holder with admin on a matching pattern is refused its suspend and resume. A root admin is allowed.
  • Delete still removes a workspace in workspaces/, with its entry.
  • A hand-written deleted for a workspace of the operator's own leaves its folder untouched.
  • A wanted file that says active, left behind under a name that is imported later, starts nothing.
  • A registered folder that is the root's repo gets no second serve.
  • A host started with a registry that cannot be read starts each workspace whose wanted file says active, in the folder that file names or stands for.
  • A host started with no registry file and an empty workspaces/ lists nothing and creates no registry file.
  • The wanted files in an existing host folder are byte for byte what they were after a suspend and a resume by request.
  • The access suites cover the refusals.
  • The host's 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/workspace_reconciler.ts and src/serve/host/serve_host.ts for what is listed and started.
  • src/domain/serve/hosted_workspace.ts and src/infrastructure/persistence/hosted_workspace_file_repository.ts for the wanted file, and src/serve/host/status_writer.ts for the status file's reason.
  • src/libswamp/hosted_workspace/ for the services.
  • src/serve/handlers/workspace_handlers.ts for authorization, and src/cli/serve_workspace_request.ts for the client's codes.
  • src/domain/workspace/ and src/libswamp/workspace/workspace_store.ts for the registry.
  • design/surfaces/workspace.md for the registry's own rules.

Out of scope

  • A host with no host folder. That is swamp-club#4920.
  • Creating a workspace anywhere but workspaces/. That is swamp-club#4921.
  • Registering a repo through a request. A request can create a workspace, never import a folder: registering an existing repo is an act of the host's user on the host's machine.
  • The registry's trust mark. It is about agents and does not gate serving.
  • Repointing clients, workers and checkouts that used another address for the repo. Their owners do that.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 16 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/20/2026, 6:38:47 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/20/2026, 2:40:46 PM

Sign in to post a ripple.