swamp serve has multiple levels of run durability depending on the deployment stack — filesystem datastore (local only), remote datastore without control-plane support (local only), and remote datastore with control-plane support (cross-machine HA). Today, the operator has no visibility into which level their deployment actually provides. They configure a datastore and vault, start serve, and hope for the best.

Mismatches are silent. An operator running S3 datastore with a file-based vault gets durable runs but secrets that vanish on instance replacement — workflows that depend on secrets will fail on the replacement instance with no warning at startup.

Desired Outcome

On startup, serve probes its deployment stack (datastore type, control-plane capability, vault type), resolves the durability mode, logs it clearly, and warns about mismatches. The operator sees exactly what their deployment supports without reading docs.

This is informational only — no behavior change. The --detach-runs flag stays as-is. Flag deprecation and auto-detection of HA mode are tracked separately.

What to implement

Mode resolution logic

Serve checks three things at startup:

Datastore type — filesystem or remote (custom extension)?
Control-plane support — does the sync service advertise controlPlane capability?
Vault type — none, local/file-based, or remote (AWS SM, etc.)?

These resolve to a durability mode:

#	Datastore	Control-plane	Vault	Mode	Notes
1	Filesystem	n/a	none/local	local	Developer laptop. Runs survive disconnection + same-machine restart.
2	Filesystem	n/a	remote (AWS SM)	local	Vault doesn't affect run durability. Machine death loses runs.
3	Remote (S3)	no (old extension)	any	local	Warn: update extension for cross-machine durability.
4	Remote (S3)	yes	none	durable	Warn: no vault configured — workflows requiring secrets will fail.
5	Remote (S3)	yes	local/file	durable (limited)	Warn: secrets won't survive instance replacement.
6	Remote (S3)	yes	remote (AWS SM)	durable	Full HA. Everything survives instance death.

Startup log output

The mode and warnings are logged after the datastore and vault are initialized, before the server starts accepting traffic.

Scenario 6 — fully durable: [INF] serve: Datastore: @swamp/s3-datastore (control-plane: available) [INF] serve: Vault: @swamp/aws-sm-vault [INF] serve: Mode: durable — runs survive instance replacement

Scenario 1 — local filesystem: [INF] serve: Datastore: filesystem [INF] serve: Mode: local — runs survive process restart

Scenario 5 — mismatch warning: [INF] serve: Datastore: @swamp/s3-datastore (control-plane: available) [WRN] serve: Vault is file-based — secrets will not be available after instance replacement [INF] serve: Mode: durable (limited) — runs survive but secret-dependent workflows may fail

Scenario 3 — extension needs updating: [INF] serve: Datastore: @swamp/s3-datastore (control-plane: not available) [WRN] serve: Update @swamp/s3-datastore for cross-machine durability [INF] serve: Mode: local — runs survive process restart only

Scenario 4 — no vault: [INF] serve: Datastore: @swamp/s3-datastore (control-plane: available) [WRN] serve: No vault configured — workflows requiring secrets will fail after instance replacement [INF] serve: Mode: durable — runs survive instance replacement

JSON mode output

The listening event should include the resolved mode: {"status":"listening","host":"127.0.0.1","port":9090,"mode":"durable",...}

/ready endpoint

New endpoint that returns 200 only after startup validation, reconciliation, replay, and heartbeat registration are complete. The ALB/k8s health check targets /ready so traffic isn't routed to an instance that's still recovering state.

/health continues returning 200 immediately (liveness check, unchanged).

How to detect vault type

The vault configuration is in .swamp.yaml under the vaults/ directory. Each vault has a type field (e.g. "file", "@swamp/aws-sm-vault"). Check whether any configured vault uses a remote type. If no vaults are configured at all, that's the "none" case.

The detection doesn't need to be exhaustive — classify as:

"none" — no vaults directory or no vault definitions
"local" — all vaults use the built-in file type
"remote" — at least one vault uses a custom extension type (e.g. @swamp/aws-sm-vault)

How to detect datastore type and control-plane support

The datastore config is already resolved by the time serve starts. Check:

datastoreConfig.type === "filesystem" → filesystem
Otherwise it's a custom/remote datastore → check syncService.capabilities?.().controlPlane

This logic already exists in serve.ts for creating the control-plane store — reuse it for the mode resolution.

Scope

This issue is ONLY the informational logging and /ready endpoint:

Probe datastore and vault configuration
Resolve and log the durability mode
Warn about mismatches
Add /ready endpoint
Include mode in JSON listening output

This issue does NOT include:

--detach-runs deprecation (separate issue)
Auto-detection of HA mode / removing the flag (separate issue)
Any behavior changes — all existing behavior stays exactly as-is

Files to modify

src/cli/commands/serve.ts — mode resolution logic, startup logging, /ready endpoint, JSON output

Testing

Unit test: mode resolution for each of the 6 scenarios
Binary test: verify startup logs show the correct mode for filesystem vs S3 datastore
Binary test: /ready returns 503 during startup, 200 after completion
Binary test: /health returns 200 immediately

Parent issue: #1448

02Bog Flow

Shipped

8/3/2026, 11:05:08 PM

Click a lifecycle step above to view its details.

03Sludge Pulse

stack72 assigned stack728/3/2026, 9:27:05 PM

Document --restricted-commands flag for swamp serve

vault put: pass tags through to extension provider CreateSecret/setSecret calls

Docs: update manual for 23 new --server commands

Update VaultProvider interface in @systeminit/swamp-testing to support optional tags in put()

Docs: document --grants-file flag for swamp serve

Docs: document --server support for serve reload

Docs: add --tag flag to vault put reference

Docs: update manual for --detach-runs deprecation and HA auto-detection

Document the Codex plugin in swamp docs

Add --server support to CLI commands missing it

Document the swamp Claude Code plugin in the swamp documentation

Make --server a global CLI option

Add --server support to model cancel (server-side run cancellation)

Load grants from external source on swamp serve startup

swamp vault put should support tags for secret governance

Improve hot reload of the deamon, include extension source/bundle changes

Authenticated users must re-login after swamp serve restart

Add --server support to serve reload

Harden queue claim semantics: atomic claims + status-guarded markDelivered/markFailed across app queues

Auto-detect HA mode and deprecate --detach-runs flag

version-drift check (from #236) is a raw string-inequality, false-positives on multi-model manifests and metadata-only bumps

Resend newsletter audience sync: contacts, segments, backfill, unsubscribe sync-back

Move per-login token secrets from vault to encrypted control-plane store

Docs: document macOS TLS trust limitation and SSL_CERT_FILE workaround

Validate swamp serve deployment stack on startup

Docs: serve config file (.swamp/serve.yaml) and --config flag

Serve config file — read swamp serve configuration from YAML

Deno runtime does not trust ISRG Root YR — extensions fail with valid Let's Encrypt certs

Docs: update hot-reload reference to include trust list refresh

Cross-instance client re-attach for multi-instance swamp serve

vercel codegen: inline rawSyncResult in non-unwrap sync path

vercel codegen: unused listAll import blocks extension publish for 4 models

vercel codegen: add round-trip idempotency test for the pipeline

Operatives button on Collectives page does nothing

Track active runs in the control-plane store for cross-instance visibility

validateGlobalArgInputRefs checks step-level inputs but step schema rejects 'inputs' key

Docs: document continuous reconciliation and multi-instance serve flags

Docs: update workflow guard skip output to include guardExpression and guardResult

Make it aware hot reload on the deamon does not take into account trust list changes, or do take into account the trust list for the hot reload.

workflow validate: new 'GlobalArgument input references' check resolves model-definition ${{ inputs.* }} against workflow inputs, false-failing steps that supply the input

Continuous reconciliation for multi-instance swamp serve

Split the score-read circuit breaker so leaderboard pressure can't blank profile scores

oauth_sign_in telemetry records provider as the literal ":id" for every event

Ghost profile bypasses the score-read seam and 500s on a slow ledger

Profile score section blocks the render on a ClickHouse read

Council: set the scoring balance — command tiers, farm-decay parameters, cross-category ratio

Scoring coverage gaps: instrument drop-off, score ripples/mentions, reward invite-converts

Push down the two cheap leaderboard scans: ghost-gate dictionary and eventCounts owner filter

Materialize an active-days-by-id table for the streak board

score-rollup-projector: O(all-time ledger) closure + per-pod fan-out saturates prod ClickHouse CPU

Startup cache hydration for swamp serve instance replacement

Output a log line for steps skipped due to guards

extension quality scorer misreads a template-literal import specifier in generated code as an unresolvable bare import, hard-erroring the whole extension as UNSCORABLE

Add @swamp/kubernetes/statefulset model type

Docs: access token commands reference says plaintext is 'shown once'

Document --restricted-model-types flag for swamp serve

swamp auth server-login ignores SWAMP_SERVE_URL

s3-datastore extension: pullChanged writes namespace-stripped paths to local cache

serve oauth: an unrecognized device-token error kills the whole serve process instead of the bootstrap

s3-datastore: bidirectional sync pull writes namespace-stripped copies to cache root, wedging push with no supported recovery

CLI reports 'HTTP/2 not supported by this client' when the server actually returned 401 — masks auth failures as a transport error

access token mint: allow reusing a revoked token name

extension quality --json exits 1 with 'rubric factors missing' even when a full score was computed (unearned factor, not uncomputable)

serve oauth: startDeviceGrant discards the OAuth error field, making device-code failures undiagnosable

access token rotate: add --vault flag to override inherited vault

Extensions without a repository can't receive issues — including the issue asking them to add one

serve oauth bootstrap: device flow rate-limited to a 45-second window by validateClient counter, shared globally across tenants

workflow edit: after saving an invalid workflow, re-running edit reports "Workflow not found"

Authentication via Google Broken

Plus-addressed emails stripped on invite acceptance, breaking collective join and quest reward

Profile edit broken on Safari

Configurable write paths for object-creating commands (repo-relative swamp root)

Docs: document rollbackOnFailure with safety guidance for external-dependency models

Remote execution tutorial: sample runner output is missing the stdout line that #1462 restored

seadex-latent-bugs: latent product bugs pinned by the wave-2b test backfill

Remote step stdout is not streamed to the workflow runner (log artifact is transferred correctly)

Redactor false positives: HH:MM:SS timestamps masked as IPs, SHA-256 digests masked as secrets (both inside code fences)

Remote execution tutorial: worker token list output and inline workflow-summary block no longer match CLI output

Add rollbackOnFailure for method-level write atomicity

docs: working-with-data tutorial uses removed depends_on step key, blocking the tutorial