When the CLI cannot determine a collective token's scopes — because the startup whoami to swamp-club.com failed (DNS error, connect failure, timeout, 5xx) — team-feature pre-flights report:

Error: Your collective token lacks the datastore:* scope.

The token actually has the scope. The real (network) error is silently discarded, so the user is sent to swamp-club.com/collectives to re-mint a token that was fine all along. On headless/ephemeral environments this is a day-loser: the same token passes on one machine and "lacks the scope" on another, which reads as a token or server-side scope bug, not the network hiccup it is.

Where (source)

Verified at stable 20260724.175725.0-sha.00d0edb5; still present on current main (10943ef).

src/cli/mod.ts:1337-1380 — startup scope resolution when SWAMP_API_KEY is set: try ~/.config/swamp/scope_cache.json, else live whoami with a 10s AbortSignal. The entire block is wrapped in a bare try { … } catch { /* Best-effort — don't block CLI startup */ } — any thrown error (DNS, TCP, timeout, HTTP 5xx via UserError) is swallowed with no logging, leaving authScopes undefined. Two more silent paths: a 401 makes whoami() return { authenticated: false } so setAuthScopes is never called, and a 200 without a scopes field sets setAuthScopes(undefined).
src/cli/auth_context.ts:85-98 — requireScope(scope) throws missing_scope ("Your collective token lacks the X scope") whenever collectiveToken === true && authScopes === undefined.
Call sites are pure client-side pre-flights on that in-memory state: datastore_setup.ts:235, vault_create.ts:87 (via the shared helper), serve.ts:962.

Net effect: four unrelated failure modes — network unreachable/timeout, HTTP 5xx, 401, and a 200 missing scopes — all render as the same "lacks the scope" message. Only "200 with scopes that don't include X" genuinely means what the message says.

Deterministic repro

export SWAMP_API_KEY=[REDACTED-SECRET-1]        # valid collective token WITH datastore:* scope
export HOME="$(mktemp -d)"                # fresh: no auth.json, no scope_cache.json
export SWAMP_CLUB_URL=https://[IP-1]:9 # unroutable -> startup whoami fails
swamp datastore setup extension @webframp/postgres-datastore
# -> Error: Your collective token lacks the datastore:* scope.

Unset SWAMP_CLUB_URL (reachable swamp-club.com), same token, same command: passes the pre-flight. Any transient real-world network failure during the 10s window reproduces the same false message — no env override needed.

How we hit it

Headless Firecracker microVM guests authenticating with SWAMP_API_KEY only. Every boot starts with a fresh HOME → empty scope cache → mandatory live whoami through a NAT'd guest network that is occasionally flaky. Result: the token is "rejected" in the guest while the identical bytes pass on the (network-healthy) host — and after the host's first success, scope_cache.json makes host runs zero-network, deepening the false impression that the token itself differs per machine. We rotated/re-minted perfectly good tokens before reading the source.

Expected

Distinguish "could not verify scopes" from "verified and missing": e.g. Could not verify your collective token's scopes (whoami: <underlying error>). Retry, or check connectivity to swamp-club.com. with its own error code (scope_unverified), keeping missing_scope for the genuine case.
Report a 401 as an authentication failure, not a missing scope.
Log the swallowed whoami error (warn/debug) instead of discarding it in the bare catch.
Optionally: retry the whoami once at requireScope time when scopes are unresolved, since a single 10s startup attempt is the only shot per invocation.

Context

The scope gate is new: shipped in swamp PR #1934 and hot-fixed the same evening by PR #1936 — whose commit message documents three earlier causes of this exact false "lacks scope" symptom (username guard, --unstable-bundle state duplication, auth.json clobber). This is a fourth, environmental one; the pre-flight seems like a prime candidate for the E2E UAT tracked in Lab #1375.

Workaround we use meanwhile: pre-seed ~/.config/swamp/scope_cache.json with {"fingerprint": "<first 12 chars of the token>", "scopes": ["datastore:*", "vault:*"]} so the pre-flight passes without a live whoami.

Environment

swamp stable 20260724.175725.0-sha.00d0edb5 (also inspected main @ 10943ef)
Linux x86_64 (microVM guest, fresh HOME per boot) and macOS 14 host
Auth: SWAMP_API_KEY collective token (swamp_org_…) minted via swamp auth token create --collective … --scopes datastore:*,vault:*

02Bog Flow

Closed

7/25/2026, 12:27:46 AM

No activity in this phase yet.

03Sludge Pulse

stack72 assigned stack727/24/2026, 9:15:49 PM

stack72 commented 7/25/2026, 12:27:46 AM

@magistr Thanks for the detailed reports — we appreciate the work you're putting in to make the tool better. Fixes are in #1960 and will be released shortly.

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

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

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

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

Docs: document datastore directory relocation during setup

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

Expose resource attributes in DataHandle for workflow report stepExecutions

Expose workflow inputs in WorkflowReportContext

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

docs: update giga-swamp guides and skills for setup extension --namespace

Quest page: all leaderboard usernames show 'Swamp Baby' title

Website extension search ignores API relevance — exact name match "good-planning" ranks #10 (API ranks it #1)

Extension/type search at method granularity — find capabilities, not just packages

data query and data get return the same payload under different keys

forEach leaves self.* unresolved in target

It is possible for a member to be a member of a collective twice

swamp-club: score-reads tierTotals GET overflows URL with inline param_ownerIds (Invalid URL, mislabeled clickhouse-network-error) for large collectives

Docker-related model types/workflows would benefit from first-class dry-run/plan support

Hide enterprise (SSO) operatives from announcements and leaderboard by default

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

Published extension scores dependency-trust as "missing" (0/2) while client `extension quality` earns it (2/2); no verdict exposed

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

namespace unset --migrate silently deletes artifact history via catalog-rebuild GC (~484k files lost)

serve: workflow.approvals and workflow.run.search still full-scan the workflow-run store after the #1284 data.query pushdown

Bugs filed by a team-subscription user are not tagged "team" in the Lab

Bundled extension model cannot deserialize AWS SDK S3 XML that works in direct Deno

gcp/sheets spreadsheets-values: batch_get crashes with "Request with GET/HEAD method cannot have body"

Token creation API and UI scope selector for collective tokens (phase 4 of #960)

Make Cloudflare CRUD methods factory-aware so list-discovered resources can be managed in-place

[sc] quest-grant Mongo ops (recentHeartbeat/signalCounts/countIssueShipped) regressed to ~5s timeouts — missing index

Add @swamp/kubernetes/statefulset model type

Sync guard skips bound namespace directory during push — 0 files pushed after namespace migrate

Flaky #1052 preparePush test: mtime-granularity race on Linux tmpfs

command/shell renders JSON-object stdout lines as the literal string 'undefined'

Issue redactor treats the MongoDB authSource parameter as a secret, corrupting reproduction steps

Docs: document repo root resolution from subdirectories

Expose the swamp.club feed as an RSS feed

Grant revoke is never applied to the running server — under `--grant-reload auto` and `manual` alike, a revoked grant stays in force until an explicit `access reload`