stagecraft examples: the release gate says which SHA goes in commit and which in mergeCommit
stagecraft: start on a claimed key takes the claim's externalRefs, and a terminal work item can be given its ticket
SWAMP_SERVER_TOKEN does not authenticate with --server, while --token and SWAMP_SERVER_TOKEN_FILE do
Add-on methods (export const extension) are not found when a step is placed on a worker
stagecraft: a reconcile view that cross-checks reality (git ancestry / registry) against work-item and ticket status
A hung stagecraft publish holds a tracker's datastore lock 15+ min; after the holder dies the lock stays orphaned and run doctor reports the datastore healthy with no way to release it
serve: the cron-fire dedup claim has no deadline, so a hung control plane stalls every scheduled fire
serve: a capability probe answered by a follower does not speak for the leader that handles the forwarded request
data prune through serve deletes data of an auto-definition whose declared type is invalid
A serve host with no root in host.yaml makes its root an ordinary workspace, registered like any other, with serve's default auth
extension rm misses dependents that pin the removed extension as name@version
workspaceHub app-socket integration test expects the child's echo before the hub's own refusal
Team mode: a follower serve's commits.db WAL is never checkpointed and grows about 1 GB a day (1.7 GB after 2 days), and filled the disk
Team mode: a booting serve blocks its event loop for 21-51 s on a large datastore, longer than the writer lease's 25 s lapse, so a standby can take over mid-boot
swamp workspace import silently takes a serve host's workspace offline when its folder or name is in the host's workspaces folder
Remove the serve host's host folder layout and --host-dir: the host always reads host.yaml from the config dir and serves the registry's workspaces
serve host: a host's own workspace is suspended on an unreadable wanted file on macOS (folder spelling), and a workspace hub test assumes reply order
@swamp/cfgmgmt firewall/apt_repository/ssh: follow-ups from #4840 verification review
stagecraft studio: the default look passes axe and WCAG AA for graphics (journal tick contrast, graph tree ARIA, panel keyboard scroll)
Hosted workspace create answers host_error, not already_exists, when a plain file holds the name in the workspace location
A host-created workspace's wanted file records the repo it was made for, so a new repo at the same path is never the host's own
serve HTTP action follower test flakes: one person's rate limit through a follower can fail with 'the caller reached the limit'
The first swamp serve host run creates host.yaml in the config dir with reasonable defaults instead of exiting
Forms submit natively before their island hydrates, reloading the page and wiping what was typed
A serve host with no host folder creates workspaces in the workspace location
ensureReadSet downloads every text resource of a referenced model, not just the instances an expression reads
serve resolves realpath for thousands of files under .swamp/outputs/swamp/worker/set_status
stagecraft studio: a repository can define a theme (colours, fonts, corner rounding) for its studio
swamp serve host runs without a host folder: host.yaml in the config dir and its state in the data dir
stagecraft: a read of what the current stage expects (prompt, products and their fields, gates)
Streaming resource writes from workers through the serve data plane
Streaming resource writes from behaviors with no single-string size ceiling
data query --select reads only the content paths the expression needs
Workflow steps parse every written resource in full, and past the V8 string limit their outputs are silently empty
Flaky test: serve host registry 'a repo imported while the host runs is listed stopped...' reads no status file after the workspace already answers stopped
Flaky test: startLoadedWorker 'a Worker that loads at once starts once and answers' times out loading its fixture under load
@swamp/cfgmgmt firewall: placing a deny with first or before can lock out the run's own SSH session
@swamp/cfgmgmt: SSH ControlMaster sockets and pins ignore TMPDIR (hard-coded /tmp)
@swamp/cfgmgmt apt_repository: gpgKeyUrl writes keyring with umask-dependent perms (640 on umask-027) -> apt signature verification fails
cfgmgmt firewall (iptables): rule placement with before, after and first
stagecraft: factory definitions can take prompts and skills from repo files
A v3 write command waits the full sidecar start deadline after the supervisor it launched has already exited
Oversized resources are accepted silently at write time, then crash later runs with a V8 out-of-memory and no diagnosis
DataQueryService.refreshTypes test fails: its interleaving reader never runs during the refresh
stagecraft: a dispatch's product write records its usage, usage stays complete across subagents, and onBehalfOf is recorded consistently
Registered workspaces: a workspace registered anywhere on the machine is listed on the serve host and served in place on resume
Docs: resourceSize limits in .swamp.yaml and data query --sort size
CEL model.<name>.resource loads every latest resource of the behavior, not just the one referenced
data query --select content and foreign-content hydration load oversized items without the resource load guard
Test flake: v3 replication 'an owned sidecar whose owner's pid names another process stops' fails with 'the Litestream sidecar did not start in time' under load
stagecraft studio: Inspect shows each stage as a field explorer, not YAML
Add built-in JSON query support to the Swamp CLI
Extension push: a registry 5xx reads as the user's fault and gives no next step
`swamp data query --json` fails with "Invalid string length" once results exceed V8's maximum string length
stagecraft: dispatch prompts read injected products by latest record, not the version the run indexed
stagecraft DESIGN.md: say the stored-as-received check catches only a redacted secret, and --literal-inputs is what stops evaluation
stagecraft skill: gate summaries at the decision point, systemPrompt on workflow and behavior stages, claim's key, in-flight definition changes
Flaky test: workspaceHub a busy child is not stopped until its runs end times out waiting for the hub to ask the busy child again
extension push: content hash still depends on the extension's folder with paths.base: manifest (review report reported missing)
Flaky test: DataQueryService.refreshTypes re-reads only the given types fails intermittently when its 0 ms timer never fires during the refresh
swamp serve data.query builds its whole response as one WebSocket frame, so a remote query past V8's string limit fails on the server
swamp data get --json fails with Invalid string length on one record whose pretty-printed content passes V8's string limit
v3 bucket writer intermittently refuses with a false 'another user or host runs this datastore's Litestream sidecar' when a stale presence record from another kernel or pid namespace meets its own just-launched supervisor
Store large values once: content-addressed sharing across resources and versions
Bounded-memory access to large resources from behaviors: partial reads and streaming writes
Work-item commands run from the wrong repo report the work item as not started
stagecraft: an empty, never-started instance takes a work item's key, so claim falls back to <key>-<tracker>
swamp data get and data versions report Behavior not found for data whose behavior definition was deleted
Scheduled flaky-test detection is failing
The serve host takes its workspaces from the workspace registry, with no change to what it serves
Tailnet: developer machines can reach each other's tailscale serve by default
A serve host registers the workspaces it runs in the workspace registry, where they are
stagecraft: publish to the bound tracker after each write, and infer workItem
Team mode: a far member's large-output save takes about 2.5x v2, all in the single-connection upload to serve
Docs: the serve workspaces design keeps one list of workspaces, the registry, and a host needs no host folder
Test flake: v3 replication 'an owned sidecar whose owner's pid names another process stops' fails with no control socket under load
Flaky test: serve host 'a delete interrupted before or during the removal finishes at the next start' reports a never-announced workspace as removed
Scheduled flaky-test detection is failing
stagecraft: writes print a short status by default; full output on request
Workflow pre-validation refuses a method argument supplied as a global argument when the definition authors a methods.<method>.arguments block
Flaky test: hosted workspace lock test loses its own lock under load
The CLI signs in to a hosted workspace through the root, after one login to the host
workflow validate and run re-walk models/ once per distinct behavior name in nested workflows (follow-up to #4903)
The dashboard switcher lists a serve host's workspaces, read from workspace.list on the root
Dashboard sign-in under a workspace segment: under a serve host the page signs in to the workspace's serve
A dashboard session cookie per path: a serve with a path in its address names and scopes its cookie for that path
workflow validate and workflow run re-scan models/ once per distinct step behavior (O(steps x definition files) file opens)
behavior validate re-scans models/ once per distinct expression model reference (O(references x definition files) file opens)
@swamp/ssh: repin fails on Windows targets - POSIX `true` liveness probe not found in cmd.exe, new pin never persisted
Docs: team serve rolling restart runbook, leader takeover time, and how clients treat an inFlight refusal (#4811, #4824, #4830, #4839, #4853)
Docs: how to rotate swamp serve's TLS certificate (rolling restart on Linux, or TLS at a proxy)
Docs: a planned swamp serve restart hands in-flight runs over instead of interrupting them
Docs: swamp serve restart behaviour from #4566 (/health draining body, --reuse-port, --shutdown-listener-grace, startup not_ready refusals)
Admins aren't pinged when a profile showcase is submitted for approval
Admin panel can grant a Personal License to a collective
serve --reuse-port on macOS: the AddrInUse refusal blames 'a process listening there without --reuse-port' when the cause is the OS
workflow run --server: after reattaching to a run continued across a serve restart, the step in progress shows the reattach time as its start, so its duration is understated
swamp behavior list re-scans the extension model-definition tree once per distinct type (O(types x extension-definition-files) file opens)
Team mode: a serve booting with a cold page cache takes 109-122 s to become ready on a real-size datastore (reads about 1 GB)
A host's router turns a child's refused WebSocket into 502, hiding why the workspace or root refused it
Ship a linux-riscv64 binary (enables real swamp in the browser via unkernel)
serve refuses shell steps that splice vault.get into run on protocol 5 workers (shell_data_placement_refused)
serve hangs forever if its shutdown throws before the listener closes
serve --json --exit-on-stdin-close never exits when its host is SIGKILLed while a run is in flight
Scorecard scanCode: scan each code module once with the extension-scoring FromSites functions
serve --json never counts webhook (and likely scheduled) run outcomes in /api/v1/health metrics
workspace.list on a host root refuses non-admin callers signed in through the CLI
serve SIGTERM skips the failed-gated cleanup job of a run the user cancelled before the shutdown
serve --json writes {"status":"stopping"} to stderr instead of stdout while a run is in flight
extension-scoring: markdownImports parses every code file with Babel uncapped, and writtenSpecifiers parses them again
The sign-in exchange: a root token becomes a workspace token through a single-use code
Investigate replacing @babel/parser with oxc for parsing extension source
A workspace kind in grants: a group can be given its own hosted workspaces on the root
CLI: idempotent swamp-club requests don't retry a 503, 502, 504 or timeout, so one blip fails the push registry checks
update.restart-daemons restarts a pre-existing worker daemon with no stable cache dir into an enrollment loop
Serve links: accept and describe workspace selectors in a consented ceiling
swamp serve workspace commands: create, list, get, suspend, resume and rm
A worker daemon enabled without --cache-dir re-enrolls as a new machine on every restart, so a single-enrollment token stops it
Workspace requests on the root: serve handles workspace.*
Enrollment-token methods run from a workflow step in serve bypass the gateway's token write ordering
Default off: the serve host starts a workspace's serve only when its wanted file says active
Extension scoring blocks the API event loop for over a minute on large extensions, causing 503s on the scoring pod
Docs: enrollment token rotation now reaches workers from workflows, schedules and local rotate
Workspace services: create, list, get, suspend, resume and delete a hosted workspace
Step-lease and pending-dispatch methods run from a workflow step in serve bypass the dispatch tail's per-record ordering
serve: a follower that does not name its leader tells an inFlight serve_not_leader caller to try again
java4shell: add Windows scanning for parity with the other CVE extensions
Docs: autoupdate can restart worker and serve daemons, and set up non-interactively
java4shell 2026.11.18.1 upgrade breaks behaviors created on 2026.11.17.1
serve: a leader's serve_not_leader raised after a run start executed carries no inFlight, so clients may start it again
java4shell: recognize vendor fixed builds shipped after disclosure
workflow placement: run a workflow transparently on a specified host, local or via swamp workers (incl. nested child workflows)
workflows: a nested workflow step should inherit the caller's placement when the child declares none
sub workflow placement on workers breaks some of my extensions my
Source-run update can replace the Deno runtime
Swampify: a Preview badge on the swamp start card, and the opt-in env var goes
Add @swamp/cve/java4shell scanner for CVE-2026-114938 (Java4Shell)
Docs: nested workflows inherit their caller's placement (swamp-club#4766)
client: an HTTP action refused as serve_not_leader with inFlight is retried and can run twice
Stopped: Team mode: a member's v3 copy keeps growing under steady load even with follow-serve's-compaction (about 16 MB/h, no plateau)
Team mode: faster takeover, piece 1: a shorter writer-lease TTL (then the follower's physical copy)
Wanted and status files: suspend, resume and delete a hosted workspace
The serve host passes an OAuth client from host.yaml to its children
workflow approve: add --resume to continue the run once all gates are decided
Flaky test: webhook held delivery to a starting leader counts a third forward under load
Docs: document swamp workflow approve --resume in the manual
@swamp/cve/http2shell: old mainline RHEL 9 libbrotli z-stream builds rated check-vendor instead of vulnerable
swamp serve host: one listener that runs a serve per workspace folder
Test flake: team forwarding 'a leader that left two forwards in a row unanswered is refused at once' sometimes forwards and fails instead of refusing
Flaky under load: team forwarding test 'a leader that left two forwards in a row unanswered is refused at once' gets a may-have-run reply
Flaky under load: workflow report race, team-mode read-lock and recovery chunk-read integration tests
Tests no longer depend on Deno's npm resolver, whose TaskQueue can lose a wakeup
test: the scheduled flaky-test job skips the Litestream sidecar tests
Process-wide module state in the v3 datastore forces tests to isolate actors in Workers
test: three 'crash' tests check SQLite rollback, not crash recovery
test: test Workers that only isolate a writer lease or one command can run in the test's isolate
Scheduled flaky-test detection is failing
cve/dirtyfrag: data names use the raw host or container label, with no sanitising or clash check
A follower that forwards a v3 datastore chunk upload to its leader may get 411, because the forward drops Content-Length
swamp serve host: give each hosted workspace its own environment variables
serve: a team serve restarts one host at a time with no failed requests and no lost runs
cfgmgmt firewall (ufw): an input for rule position (insert before/after)
cve extensions: data names can still collide or be refused on Windows (trailing dots, reserved device names, case)
workflow evaluate: guard on a forEach step is over-resolved to a boolean and fails schema validation
Load serve's subcommands lazily through a serve route table
Manage the swamp-club profile from an extension behavior: a profile API and a token scope
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.