EXTENSIONS

Per-workflow observability for a swamp repo's own scheduled work.

Investigate why any swamp model or workflow is failing, without knowing anything about the domain it automates. Every method and workflow run leaves a @swamp/method-summary or @swamp/workflow-summary report behind as versioned model data, written on failure as well as success — so the full history of a target is already on disk with nothing extra instrumented. `investigate` resolves a target by name at call time, walks that history back to the boundary where it stopped working, and classifies the error into auth / unreachable / timeout / tls / rate_limit / not_found / config, each with a concrete next step. The distinction it exists to make is auth vs unreachable: a remote answering 403 is healthy and rejecting your credential (go to the vault), while a remote that never answers is a network problem (go to the host) — the two read almost identically in a notification and lead opposite ways. Unrecognised errors are reported as `unknown` verbatim rather than filed under a plausible-looking category. A run that failed without recording any error text is reported as `unrecorded`, never as `none`. `recent` answers the question an alert with no name leaves open -- what just broke? -- by listing every model and workflow that failed within a window -- still failing first, then those that have since recovered, with when -- each with its instance name and model type and classified the same way. Both methods tell the caller's mistakes apart from the fleet's failures: `recent` flags the investigator's own failed runs (selfInflicted) and a failure fixed by an immediate retry of the same method (quickRetry), reports each target's definition path, and lists scheduled workflows with no recorded run at all (a schedule that never fires leaves no failure anywhere else); `investigate` reports a target with no runs as never_run -- failing when it is scheduled to run here -- suggests the closest names for one that matches nothing, and separates a rejected call argument (caller_args) from a definition problem (config). A failed workflow step is reported with the error its own run recorded, and an expression that failed to evaluate classifies as config. `resolve` maps free alert text to the model and workflow names it most likely means -- token overlap with names, types, tags and descriptions, top matches with score -- for an alert that does not name its target. Read-only: every method reads what previous runs recorded and never invokes the failing target.

Retest the swamp-training Slidev deck when swamp ships a new release: every swamp command in the deck is checked against the release's CLI, the deck's @training/file-check lab is rebuilt from the slides and run, and the skills, CLAUDE.md and allowlist that swamp repo init installs are diffed against the last tested release. The release binary runs in a throwaway sandbox, so your installed swamp is left alone.

Fail CI when a changed swamp extension model file leaves a known invariant unencoded in its zod schema — the mechanizable subset of 'make illegal states unrepresentable', plus a set of shared zod schemas for the shapes it enforces (Sha256Digest, Platform, SshFingerprint)

Read the swamp version a host or container is running and report how far it has drifted behind the published channel. Read-only — it never updates, installs, or restarts anything; it tells you a newer build exists and stops there. Fills the gap `swamp update --check` leaves: that answers for the binary invoking it, on the platform invoking it, which is no help when the install you care about is a pinned binary inside a container on another host. `sync` records what a target reports about itself — its version and, via `uname`, the artifact platform it runs on. `drift` resolves the newest build published on a channel for THAT platform and reports status (`current`/`behind`/`ahead`) plus the lag in hours. `repoDrift` covers the second, independent axis a `swamp serve` install goes stale on — the git checkout it serves. A container can run the newest published binary while serving a branch it last fetched weeks ago, because a serve entrypoint typically fetches at boot only; `drift` reports `current` throughout and so does every healthcheck. It fetches before comparing, which is load-bearing rather than tidy: a checkout's own `origin/<ref>` is frozen at its last boot, so trusting it reports a badly stale target as up to date. It then reports the exact number of commits behind — enumerable here, unlike the binary axis, because git has the list — the lag in hours, and `current`/`behind`/`ahead`/`diverged`, keeping `diverged` distinct because the fix for `behind` is a restart and a restart hard-resets, destroying the very commits that make a checkout diverged. Targets are reached three ways: the local binary, `docker exec` (optionally through a named docker context, so one host can check a container on another), or SSH with BatchMode so an unattended run fails fast instead of hanging on a password prompt. The channel is resolved by a single HEAD against the `stable` alias, reading the resolved version out of its website-redirect metadata — one request rather than the ~90 MB the archive weighs — and the same pass verifies the platform-specific archive is actually fetchable, which is the precondition for pinning a rebuild to it. Versions are compared numerically because the build ordinal in `YYYYMMDD.HHMMSS.N` is not zero-padded: as strings `20260808.001107.10` sorts below `...9`, so a string compare reports a target one build behind as up to date the day a tenth build ships. `hoursBehind` is derived from the timestamps embedded in each version and is documented as a lag, not a count of missed builds — swamp publishes no release list, so the builds in between cannot be enumerated and this extension does not pretend otherwise. An unreachable target, an unparseable version at either end, a channel alias that answers without its redirect header, and a resolved archive that 404s are all raised as errors rather than folded into a reassuring `current`.

Fetch and parse the swamp.club leaderboard into structured JSON. Returns rank, username, score, and events count for 50 entries per page with support for pagination.