Make garbage collection a first-class, declarative datastore namespace policy that swamp serve schedules and observes. The policy should cover both existing collectors:

swamp data gc for versioned datastore data
swamp run gc for workflow-run history and model-method outputs

Today these are disconnected. autoGc: true incrementally enforces data policies after writes and model runs, while run/output retention remains manual-only. Operators must discover both mechanisms, create external scheduling, and remember to maintain it. High-frequency workflows can therefore make a repository unusable before the default manual retention window is reached.

Incident that motivated this

A valid workflow scheduled every five minutes accumulated 1,528 workflow runs in roughly six days. The local .swamp datastore reached 51 GB:

28 GB in workflow-run records
2.9 GB in model-method outputs
20 GB in versioned data

swamp serve then failed during startup with a fatal V8 out-of-memory error near the 4 GiB heap limit. Even swamp workflow history get <workflow> --json reproduced the OOM. Extensions were healthy and the workflow validated successfully.

swamp data gc --dry-run correctly found nothing eligible because workflow runs and outputs are outside its scope. The default swamp run gc retention of 30 days also found nothing because the repository was only six days old. Running swamp run gc --older-than 1d required a 16 GiB heap and a long scan, but eventually deleted 2,274 run records and 3,575 outputs and reclaimed 27.3 GB. Keeping one day still left 4.8 GB of run history, enough for the default-heap history command to OOM.

This is partly a reader scalability bug, related to #1173, but automatic retention would prevent ordinary swamp serve users from unknowingly reaching this state.

Existing pieces

#823 shipped opt-in autoGc for datastore data.
#1172 shipped the manual swamp run gc command.
#1200 explicitly documents that automated run/output retention is still a planned follow-up.

The missing piece is one policy and lifecycle for all datastore-owned garbage.

Proposed behavior

Add a validated GC policy to repository/datastore namespace configuration, for example:

datastore:
  garbageCollection:
    schedule: "0 * * * *"
    data:
      enabled: true
    runs:
      olderThan: 24h
    outputs:
      olderThan: 24h

The exact schema is open for design. Important semantics:

swamp serve registers GC as built-in maintenance, not as a user-authored workflow or shell wrapper.
Policy is scoped to the datastore namespace so every client uses the same retention contract.
Data GC continues honoring model/report lifetime and version policies.
Run/output GC uses explicit age or count retention and always protects active, pending, and suspended work.
Only one server performs maintenance for a shared namespace through the existing datastore lock/lease mechanism.
Failures are isolated from user workloads and surfaced as structured status rather than silently ignored.
A server restart does not create a catch-up storm; at most one overdue maintenance pass runs.
Manual swamp data gc and swamp run gc remain available and use the same policy when explicit flags are omitted.

Operability

Expose the policy and runtime state through commands such as swamp datastore status --json or a dedicated GC status command:

enabled/disabled
effective namespace policy
last attempt and last success
next scheduled run
entries and bytes reclaimed
duration and error details

Provide preview and validation before enabling automatic deletion. A generated configuration should choose conservative defaults and explain expected storage based on workflow frequency.

Onboarding and agent guidance

Add a CLI generator, such as swamp datastore gc policy init, or extend datastore setup to ask about retention. Update the swamp agent skill to inspect workflow schedules and current datastore growth, recommend a policy, generate valid configuration, preview its effect, and explain the distinction between data GC and run/output GC.

The skill should improve discovery and configuration, but the feature must remain first-class CLI behavior with a schema, locking, status, and safety guarantees. Garbage collection should not depend on every user or agent independently inventing a maintenance workflow.

Acceptance criteria

A namespace can declaratively configure periodic data, run-history, and output GC.
swamp serve safely schedules and executes that policy.
Multiple servers sharing a namespace cannot run conflicting GC passes.
Active/pending/suspended work is never removed.
Effective policy, last/next execution, reclaimed bytes, and failures are inspectable.
Configuration has validation, preview, documentation, and agent-skill guidance.
GC implementations scan incrementally or stream metadata so cleanup itself does not require heap proportional to retained history.
Existing autoGc and manual commands have a documented migration/compatibility path.

02Bog Flow

Open

7/28/2026, 1:56:55 PM

No activity in this phase yet.

03Sludge Pulse

model validate: transport-reachable preflight sends unresolved vault CEL expression as credential

Add `amp` (Amp Code) as a built-in --tool for repo init/upgrade/audit

Add rollbackOnFailure for method-level write atomicity

Expose resource attributes in DataHandle for workflow report stepExecutions

Make swamp serve durable and highly available

Docs: document guard and resume --from in workflows reference

.swamp.yaml rewritten with quote style change + lastSkillMigrationWarning on read-only operations

Add --from flag to workflow resume for DAG re-entry on failed runs

data delete removes data locally but push reports 'no changes' — next datastore sync restores everything

Empty report returns persist 0-byte versions that mask the real report — and `swamp data gc` then deletes the real version, keeping the empties

Docs: document guard field for workflow steps

First-class scheduled garbage collection policy per datastore namespace

Add guard field to workflow steps for idempotent execution

--quiet mode does not suppress in-process extension logger output

tailscale transport hangs indefinitely on Tailscale SSH check-mode auth; never surfaces the login URL

Concurrent @type auto-creation races: N simultaneous runs create N definitions sharing one name, and only one is reachable

Worker queries need a safe connected-worker filter for fleet fan-out

Extension docs still ship the Driver extension type, which the binary refuses (rejectRemovedDriverFields) after #535

Docs: document vault selection for sensitive fields (defaultVault, per-resource vaultName)

azure-kv error wrapping loses original error type — ERROR_TYPE always 'Error' in traces

writeResource commits per-call: a method that fails midway leaves its earlier outputs persisted, with no marker that the run failed

Docs: document workflow-scope ReportContext fields in extension report reference

Cloudflare: expose GraphQL Analytics API (httpRequestsAdaptiveGroups / client-IP request analytics)

aws-sm deleteAnnotation removes all non-aws: tags, not just swamp-specific ones

No way to select which vault receives a sensitive-marked field's value

aws-sm: namespace annotation labels with swamp:label: prefix

workflow assert: a step whose CEL expression fails to evaluate is omitted from --junit output, so the XML reports a clean pass

Documentation for workflow assert steps and JUnit output

Expose workflow inputs in WorkflowReportContext

Teach swamp skill how to write assert workflow steps

Include a workflow's declared `inputs` in `workflow get --json` (and a `hasInputs` hint in `workflow search --json`)

Docs: add how-to guide for running swamp serve/worker in daemon mode

worker daemon enable: relative/missing --cache-dir fails launchd EX_CONFIG while daemon status reports running

swamp doctor extensions: nondeterministic BundleBuildFailed for local extensions on an unchanged tree

Docs: document datastore directory relocation during setup

vault extensions: emit OTel spans for vault operations (AWS SM, Azure KV, 1Password)

Issue redactor corrupts reports: dotted code identifiers masked as hostnames, loopback and RFC 5737 documentation IPs masked, angle-bracket placeholders half-eaten

data prune resolves auto-definitions at the local path, not the datastore path — deletes live models' data (verified: destroyed a working server token and an active grant)

workflow/job-lifetime data is never reclaimed — expiry check requires an ownerDefinition.workflowId that step execution never sets

runModel breadth limit (MAX_INVOCATION_BREADTH=100) is never enforced — tracking object is never written back to the caller context; verified 150/150 calls succeeded

serve daemon enable is ungated — it reports success, then the account gate fires inside the detached daemon, which crash-loops invisibly

Purely local operations require a swamp-club account: local-token serve is gated while deprecated --auth-mode none is not, third-party OIDC is gated, and 'Local_Encryption' is paywalled by capitalization

A collective token stored in auth.json (rather than SWAMP_API_KEY) is permanently scope-less — resolution only runs for the env var, and scopes are never persisted for collective tokens

An empty stored apiKey counts as authenticated — saveIdentityCache writes apiKey:'' on a virgin machine, permanently satisfying the mandatory-account gate with no credential

Account/scope gates fire before argument, type and repo validation — 'swamp vault create env my-vault' (the command's own example, an invalid type) returns a paywall instead of 'Unknown vault type'

auth token create advertises a 'collective:write' scope that does not exist, and following its advice hits 'collective tokens cannot create other collective tokens'

requireScope does exact string matching — fine-grained scopes fail gates that demand the literal wildcard, and minted scopes are never validated or normalized

Collective-token scope cache never expires, is never refreshed by whoami, and cannot be cleared via the CLI — scope changes and revocations never take effect

Collective-token scope cache is keyed on a 12-char token prefix — only 2 chars distinguish org tokens, so a rotated token silently inherits another token's scopes

Misleading 'Your collective token lacks the X scope' when scope resolution failed — startup whoami errors are silently swallowed

Community points / reputation: award points for upvoting extensions, feature requests, comments, and feed posts

globalArgs fields leak into method arguments when a method's arguments schema is a bare z.record()

swamp serve --auth-mode oauth: crash during first-run admin resolution discards the OAuth token, forcing full device-flow re-registration

Docs: document extension runtime permissions and device I/O workaround in user manual

datastore setup extension drops 'namespace' from --config, making extensions that require it impossible to configure

Kiro CLI v3 permissions: no capability covers disclose_context (skill loading)

CLI: swamp invite <email> to drive the platform-invite API

api-key-scoping explanation doc contradicts shipped fine-grained scopes

Fine-grained scopes for swamp.club access tokens

End-to-end UAT for fine-grained collective token scopes (#960)

Docs: document swamp auth token create command for collective tokens

open method fails for password-auth hosts: SSHPASS env set but ssh call never wrapped in sshpass

docs: update swamp skills for setup extension --namespace

apps sync/lookup fail with 'partial() cannot be used on object schemas containing refinements'

Docs: update autoGc documentation to reflect write-time version pruning

model search/list doesn't enumerate auto-created definitions under .swamp/auto-definitions/

CLI command to create scoped collective tokens (phase 8 of #960)

docs: document auth gates for team features (datastores, vaults, serve)

`datastore setup filesystem` never transfers content when leaving a sync-based (remote) datastore — copies only the catalog and hardcodes `filesPulled: 0`

Workflow/CLI output uses red text for non-error/informational lines, contradicting standard error-color convention

Support end-user timezones on https://swamp-club.com/u/shelson/activity

Document doctor datastores --repair for namespace contamination cleanup

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

Pre-flight checks receive unresolved vault.get() expression text, not the resolved secret

Invite people who have never used swamp to a collective (email invite flow)

docs: update giga-swamp manual pages for setup extension --namespace

Docs: update extension push output examples to include channel and visibility

Collective management API for extension-based automation

Remote --server wss:// fails through an HTTP/2 TLS reverse proxy (WS client ALPN is h2-only)

uat: add namespace isolation and shard resilience test coverage