Relationships
#4325 Team mode manual pages: swamp-serve and remote-execution for leader/follower, member checkouts, offline work, run control and known limits
Opened by stack72 · 11/2/2026
Summary
The swamp-club manual pages for serve and remote execution are stale for team mode (v3 through serve). They live in the swamp-club repo under content/manual/. Split out of #4320, which covers the help text, design docs, skills and the serve-start warning in the swamp repo. Docs only.
Pages:
content/manual/explanation/swamp-serve.md,how-to/swamp-serve.md(andhow-to/swamp-serve/),reference/swamp-serve.md(andreference/swamp-serve/)content/manual/explanation/remote-execution.md,how-to/remote-execution.md,reference/remote-execution.md(andreference/remote-execution/),tutorials/remote-execution.md
What to cover
- One name. User-facing text says team mode. Do not use "serve-mode checkout" in the manual.
- Team mode requires
managedConfig. Definitions live in the datastore. A workflow whose behaviors exist only in a member's git checkout is refused by serve ("a step output names data of a behavior that does not exist"). Say this in the setup pages, and mention the warning serve prints at start on a team datastore withoutmanagedConfig(added in #4320). - Leader and follower,
--advertise-addressand--ca-cert. - A member's checkout:
serverAddressand a token, no storage credentials. - Offline work and leases.
- What runs locally and what goes to serve. Local: method and workflow runs,
extension install. Serve: approve, reject, signal, and cancel of a run the checkout didn't start. - Run control in team mode.
workflow approve,reject,signal,cancelandwaitsgo to serve in a team checkout.- Signal-wait workflows are refused in a member checkout before they start. Run them with
--server, or from a trigger or schedule. - For a gate that must bind its runner, run the workflow on serve.
- Link the threat model ("Run records: the threat model" in the access-control design doc).
- Known costs and limits, stated plainly:
- a step start commits before the step runs, with its measured cost, until the constant-size marker ships;
- two checkouts sharing a filesystem datastore no longer stop each other's runs (#4274);
- a member can't change a behavior's type through an edit (#4294);
- a gate's freeze holds within one wait, not across a retry.
Done when
A new team member can set up a checkout, run, approve, work offline and recover a run from the manual alone, and every term matches the CLI help text shipped by #4320. Check commands and flags against swamp help <command>.
Open
No activity in this phase yet.
system commented 11/2/2026, 9:48:33 PM
Classified automatically when this issue was filed.
- Source: Swamp Club
If you feel this classification is incorrect, add a ripple to tell us so.
Sign in to post a ripple.