The swamp serve dashboard needs two new endpoints that don't exist today: one to list all instances in a cluster, and one to expose the serve configuration. Without these, the System view's cluster table and serve config panel cannot be built.

Proposed Changes

1. Add `cluster.instances` endpoint (P1 — Blocker for cluster view)

Add a WS command cluster.instances and/or REST GET /api/v1/cluster/instances that reads all heartbeat records from the ControlPlaneStore and returns them.

What exists today: The InstanceHeartbeatService in src/serve/instance_heartbeat.ts already writes HeartbeatRecord objects (instanceId, hostname, pid, startedAt, heartbeatAt) to the ControlPlaneStore under the heartbeats/ prefix. The store supports list("heartbeats/") to enumerate all instances. But no API handler reads this data.

What the endpoint should return per instance:

instanceId — the unique instance identifier
hostname — machine hostname
pid — process ID
startedAt — when the instance started
lastHeartbeatAt — last heartbeat timestamp
status — derived: "healthy" (heartbeat within threshold), "degraded" (heartbeat stale but recent), "unreachable" (heartbeat expired)
address — the instance's serve address (host:port) if available, so the dashboard can fan out SSE connections for cross-instance metrics

For the connected instance, enrich with the full health snapshot data (metrics, activeRuns, workers, components) since we have it locally.

Dashboard panels this unblocks:

System view → Cluster Instances table (instance ID, status, mode, uptime, active runs, throughput, P95, workers)
Sidebar → Cluster section showing all instances with health dots
Overview → "3/3 healthy" status pill
Cross-instance health aggregation (dashboard can connect to each instance's /api/v1/health/stream once it knows the addresses)

Files: New handler in src/serve/handlers/ or src/cli/commands/serve.ts, reading from ControlPlaneStore

2. Add `serve.config` endpoint (P2 — Blocker for system view)

Add a WS command serve.config and/or REST GET /api/v1/config that returns the resolved serve configuration with secrets redacted.

What exists today: MergedServeOptions is computed at startup from CLI flags + serve.yaml + environment variables, but is consumed during setup and never stored for later querying. The health endpoint includes some of this data (deploymentMode, scheduling.enabled, webhooks[]) but not the full picture. Auth mode is on GET /auth/info. Port, host, TLS status, and the original CLI flags are not queryable at all.

What the endpoint should return:

port — the port serve is listening on
host — the bind address
tls — { enabled: boolean, certPath?: string } (key path redacted)
authMode — "admin-token" | "oauth" | "none"
scheduling — { enabled: boolean }
dashboard — { enabled: boolean }
webhooks — array of { route: string, workflow: string, scheme: string } (secrets redacted)
maxConcurrentRuns — if configured
enableInternalApi — boolean
repoDir — the repository directory path
extensionsDir — if overridden
datastoreType — the configured datastore type

Implementation: Capture the resolved MergedServeOptions at startup and store it on the serve context (or a dedicated config holder) so the handler can read it later. Redact adminToken, webhook secrets, TLS key contents, and any other sensitive values before serializing.

Dashboard panels this unblocks:

System view → Serve Configuration card (port, TLS, auth mode, scheduling, dashboard flag)
System view → Serve Flags display (the CLI flags with redacted secrets)
System view → Webhook endpoints list

Files: Capture in src/cli/commands/serve.ts at startup, new handler in serve handlers

Context

Part of the swamp serve dashboard initiative. These two endpoints complete the System view alongside the schema changes in #1710. The remaining gaps (health snapshot activeRuns enrichment, worker.list enrichment) are separate concerns that can be follow-up issues.

02Bog Flow

Shipped

8/19/2026, 1:38:51 AM

Click a lifecycle step above to view its details.

03Sludge Pulse

stack72 assigned stack728/18/2026, 10:39:15 PM

data prune still misclassifies live records as orphans on 20260820 (after #1396) — serve-minted token/grant records, and report data of every live workflow

wss:// direct to serve's own TLS listener still fails on 20260817 — client ALPN lands on h2, WS-over-h2 unimplemented (follow-up to #1363)

Concurrent pushes to one namespace fail with HTTP 409 ConditionalRequestConflict — the conditional PUT is never retried

serve: triggerSource not persisted to workflow run summary

dataOutputOverrides not applied during remote execution — ephemeral resources GC'd before override takes effect

extension rm also deletes the lockfile entry, and install on an empty lockfile is a silent success — rm/install is not a round trip

vault: audit trail should record put, delete, and annotate operations

ExtensionWorkflowRepository scans manifest.yaml as a workflow, emitting 'Unknown key manifestVersion' warning

--max-run-duration only applies to detached runs, not attached runs

Cancel endpoint reports status: cancelled for runs it did not actually cancel

@swamp/git: no way to amend a commit, but push can --force

Installation with new account creation times out

pre-flight checks run on orchestrator, not on worker — breaks remote execution with filesystem-dependent checks

Docs: update cancel endpoint response statuses in REST API reference and workflows page

docs: document --remote-only flag for swamp serve

Swamp serve daemon doesn't run with --hot-reload

serve: include workflowName in HealthSnapshotSchedule

Retyping a model instance strands catalog rows no command can reclaim — prune matches on model_id, delete resolves the current type (follow-up to #1009)

knowledge-base retrieve persists query output into the state resource, with lifetime infinite and the query text in the instance name

Method-name collision between a base model type and an extending extension silently drops the whole extension file — no error, doctor reports pass

Skip 50MB monolithic index rewrite on v2 shard-first path

Share single AwsS3Client instance across lock, sync, and verifier

Double shard assembly per command lifecycle (pull + push both read all shards)

pullChanged never records commitSeq for shard-first (v2) index

localHasAllRemoteEntries() permanently blocks sidecar update on partial caches

serve: workflow.history.get cannot find CLI-created runs or look up by run ID

"TRIAL ENDED" modal shown to team plan user when toggling extension visibility

Concurrent suspended workflow runs can't be disambiguated from 'approvals'; fresh runs should supersede matching-input suspended runs

I _think_ I might like a guard in the trigger yaml

swamp cmds don't realise the user is sshed into the system

serve dashboard: add cluster.instances and serve.config endpoints

CEL expressions have timestamp/duration but no current-time value, so no guard can express "older than N"

Support direct type execution (@type) with --server

access token mint writes to user vault, not serve's _token-secrets control plane in HA mode

Generic OTLP endpoint appends signal path after query or fragment

Issue lifecycle start drops top-level issue comments

serve dashboard: add instanceId, triggerSource, and step progress to WorkflowRunSummary

Document worker affinity (affinity: true) for workflows and jobs

Datastore MongoDB driver leaks connections — 5960 accumulated over 8 days

workflow approvals displays the latest run's prompt for every suspended run

@swamp/git: add a read-only working-tree diff for pre-commit review

docs: document --oauth-client-name flag for swamp serve

Docs: update workflow reference to include trigger in JSON output shapes

@swamp/git branch and push methods fail data naming when branch contains '/'

Docs: update workflow-placement.md for job/workflow-level placement inheritance

feat(serve): use identifiable OAuth client_name instead of random UUID

@swamp/git does not pass AbortSignal to Git subprocesses

Global Secret Manager methods build an invalid regional parent

Document model.method() support in assert expressions

No way to store code-review results — verdicts, findings, and cost are not persisted for any repo

Redaction regex boundary bug: label_base64 secrets with an unrecognized label pass through unredacted (e.g. swamp_ API keys)

User token page (/u/<user>) shows only "swamp_..." for every API key, making leaked-key identification impossible

upstream_state treats sparse-fetch branches as having no upstream

Add native support for the Pi coding harness

Cloud Build create supplies project instead of required projectId path parameter

workflows: support labels/target/platform at job and workflow level

swamp access grant create never registers the grant — a --deny created this way silently fails open

Support credentials in datastore config (vault-resolvable)

swamp serve OOMs on repos with 2000+ model definitions

Serve telemetry attribution for collectives

Extension workflows: no way to override trigger configuration

Add a list/discover method to the generated @swamp/aws types — no way to enumerate resources in a region

Document @vault= prefix for webhook secrets in serve.yaml

swamp access grant create installs an unrelated extension from the registry

docs: document SWAMP_API_KEY headless OAuth bootstrap for swamp serve

workflow-succeeded selects the globally-latest run, so siblings block each other under parallel use

swamp serve: webhook secrets should support @vault= resolution

Misleading collective_not_trusted auto-resolve error when a local source extension transiently fails to index during workflow validate

datastore setup: symlinks not counted in bytesCopied, causing misleading '(0B)' output

vault.get() CEL error embeds raw newline when wrapped by model resolver, producing broken output

Feature: user-configurable redaction rules (.swamp/redaction.yaml)

Fatal JavaScript out of memory: Ineffective mark-compacts near heap limit

Sync every signup to Attio, and backfill the existing population (#809 follow-up)

@swamp/issue-lifecycle probes /api/health, which swamp-club stopped serving when the Fresh scaffold stubs were removed

Lab lifecycle POST rejects any payload string that starts with a dollar sign, not just operator keys

Feed: detect and gracefully handle dead (404) post links (link rot)

/feed: per-post unread indicators and mark-as-read to track reading progress

/feed: filter and search by author, title/text, and topic

Add a :micdrop: emoji / reaction shortcode (swamp-native art included)

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