Skip to main content
← Back to list
01Issue
FeatureOpenSwamp ClubPublic
AssigneesNone

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 (and how-to/swamp-serve/), reference/swamp-serve.md (and reference/swamp-serve/)
  • content/manual/explanation/remote-execution.md, how-to/remote-execution.md, reference/remote-execution.md (and reference/remote-execution/), tutorials/remote-execution.md

What to cover

  1. One name. User-facing text says team mode. Do not use "serve-mode checkout" in the manual.
  2. 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 without managedConfig (added in #4320).
  3. Leader and follower, --advertise-address and --ca-cert.
  4. A member's checkout: serverAddress and a token, no storage credentials.
  5. Offline work and leases.
  6. 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.
  7. Run control in team mode.
    • workflow approve, reject, signal, cancel and waits go 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).
  8. 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>.

02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

11/2/2026, 9:48:33 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

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.