Skip to main content

Swamp Go Brr

@magistr/swamp-go-brrv2026.07.16.2· 11d agoMODELSSKILLS
01README

An autonomous, driver-free development loop for coding agents. You hand it an intake and a host-pinned test command; it decomposes the work into a dynamic DAG of tasks, runs each task as a claude --print agent inside a throwaway Firecracker microVM, applies only the returned diff behind an allowlist ACL, and merges a task ONLY when a deterministic, network-less container says the tests pass. Nothing the agent writes ever runs on your host, and the green gate is the container's exit code — never the agent's self-report.

Five models:

  • gobrr — a PURE DAG state machine: a Run aggregate over a dynamic Task DAG (implement | verify) with a scheduler (lease TTL/heartbeat/reap, concurrency gate, stall), dynamic follow-up expansion, a state machine, and run caps. It never touches the filesystem.
  • source-integration — the host code-ownership / allowlist-ACL actor: build_workorder (read the allowlist file slice into the leaf prompt, no-clone) and apply (parse the @@EDIT envelope, apply each task as a per-task base-isolated jj change behind a realpath-anchored allowlist ACL, return host-observed changedPaths + a secret-scrubbed diff).
  • docker-verify — the deterministic green gate: runs the host-pinned verify command to completion in a hardened, network-less, token-less container against the read-only applied tree and returns the raw exit code.
  • preflight — codebase-agnostic substrate setup: ensures the local OCI registry, digest-pins the codebase's OWN gate image (pin_image builds a build context or pins a prebuilt ref — the toolkit/deps live in that image, not here), and emits the run config (gate params, fabric_up inputs, the vault CEL for the OAuth token, and the si/dv/fab create commands). Shells to docker only.
  • otlp-export — the post-run OTLP egress actor (the loop's ONLY network push; gobrr stays pure): POSTs the derived traceOtlp/metricsOtlp to a configurable OTLP/HTTP collector (https), endpoint + token from a vault CEL, best-effort. gobrr's emit_otlp derives the OTLP span tree + per-leaf token/cost/time metrics; leaves run with outputFormat=json so claude's usage rides back. Each leaf runs claude --print in a Firecracker microVM via the @magistr/firecracker fabric (no-clone). The agent drives the loop inline (next -> build_workorder -> fabric.submit/poll -> apply -> docker-verify -> report); there is no driver script.

Getting started: install the bundled swamp-go-brr skill and let the agent drive the loop — confirm the repo scope, the verify command, and the verify inputs, then it decomposes, runs, gates, and reports. The README has a tutorial, how-to recipes (per-leaf cost/tokens/time, OTLP export, resume/inspect, concurrency), a model reference, and the design rationale.

02Release Notes

Release 2026.07.16.2 — align model versions with manifests

Maintenance release across the @magistr extensions. For most packages this carries no functional change: the only edit is the model's version: field, brought back in line with its manifest version so the published model type version and the package version no longer drift.

Functional changes in this release are limited to:

  • anime-cron: normalizeTitle now strips a ": subtitle" suffix and a trailing parenthesized year before comparison, fixing dedup false-misses where the torrent title carries a subtitle or year that the AniList romaji does not.

  • arckit: first publish. Standalone ArcKit port — a 12-phase architecture governance state machine with 65 bundled templates, driven by a bundled skill.

Also tracks three extensions (kaiten, observability-agent, music-library) that previously existed only as untracked working-tree directories, recovered from stashes.

03Models5
@magistr/swamp-go-brr/gobrrv2026.07.16.2extensions/models/gobrr.ts
fn start(intake: string)
Start a run: record the human intake + the host-pinned RunConfig (verifyCommand, verifyInputs, repoScope, caps).
ArgumentTypeDescription
intakestring
fn seed_tasks(tasks: array)
Add tasks to the DAG (batch). Derives each gate from writeAllowlist ∩ verifyInputs (rejects a mixed allowlist) and rejects a dependency cycle.
ArgumentTypeDescription
tasksarray
fn next(owner: string)
Lease the next ready task to `owner` (or report all-green / halt). Reaps expired leases, propagates blocked, enforces caps.
ArgumentTypeDescription
ownerstring
fn report(taskId: string, owner: string, verifyExitCode: number, audit?: object)
Report a leased task's WorkResult + the deterministic verify exit code (and optional audit: the declared envelopeSummary + raw docker-verify verifyTail). Greens ONLY on verifyExitCode===0; rejects out-of-allowlist / verifyInputs hunks; parse-fail → infra_error. Persists the gate decision FIRST, then best-effort-appends one step-output audit record.
ArgumentTypeDescription
taskIdstring
ownerstring
verifyExitCodenumber
audit?object
fn add_followup(parentId: string, owner: string, spec: string, writeAllowlist: array)
Insert a follow-up the leased parent depends on (untrusted request: repoScope-bound, depth-capped, cycle-rejected).
ArgumentTypeDescription
parentIdstring
ownerstring
specstring
writeAllowlistarray
fn heartbeat(taskId: string, owner: string, vmId?: string)
Renew a task's lease and record its vmId (owner keeps the lease alive while the VM runs).
ArgumentTypeDescription
taskIdstring
ownerstring
vmId?string
fn hydrate()
Write a compact summary of the run (counts, halt reason + options, leased VMs, stall culprits, cost estimate) plus the derived step-output projection (record count, declared-vs-observed mismatches, reaped-invocation gaps).
fn emit_otlp()
Derive + write the OTLP observability resources: `traceOtlp` (the run->task->invocation span tree, with content.status = ok|unavailable|empty|partial) and `metricsOtlp` (per-gate leaf tokens/cost/duration/invocations). PURE derivation from the run + 7d step records (ADR 0002); gobrr never exports — @magistr/swamp-go-brr/otlp-export ships these.
fn abort(reason: string)
Halt the run (any non-terminal state). Records leased vmIds for the driver to destroy.
ArgumentTypeDescription
reasonstring
fn complete()
Mark the run complete (requires all tasks done) and emit the final report.

Resources

run(infinite)— Authoritative Run aggregate — the Task DAG + scheduler state.
summary(infinite)— Compact hydrate summary — derived from `run`, cheap to read.
decision(infinite)— The most recent next() decision — which task to run, or why halted.
stepOutputs(7d)— Append-only per-leaf-invocation audit log {records: StepOutput[]}: the raw PRUNED measurements report() was given (declared envelope summary, host-observed changedPaths + scrubbed diffTail, verify exit + scrubbed verifyTail, outcome/failureKind). One resource per run; rollups are DERIVED via stepOutputProjection, never stored. Lifetime 7d (bounded retention, issue si-applied-resource-lifetime) — longer than the transient per-task inputs (24h) so a post-halt inspection survives, while not retaini
traceOtlp(7d)— DERIVED OTLP/JSON span tree (run -> task -> invocation), produced by emit_otlp. content.status is one of ok|unavailable|empty|partial (unavailable = pre-feature run with no traceId; partial = >7d run whose step records were GC'd). Read via `swamp data get <name> traceOtlp --json | jq -r .content.status` (the OTLP body is .content.resourceSpans). Lifetime 7d (ADR 0004 — carries scrubbed attribute text). Hand-off artifact for @magistr/swamp-go-brr/otlp-export; gobrr never pushes it.
metricsOtlp(infinite)— DERIVED OTLP/JSON metrics (per-gate leaf tokens/cost/duration/invocations), produced by emit_otlp. Numeric only (no status, always fully populated; labels restricted to the METRIC_LABELS allowlist — no free-text). Read via `swamp data get <name> metricsOtlp --json | jq .content.resourceMetrics`.
@magistr/swamp-go-brr/docker-verifyv2026.07.16.2extensions/models/docker_verify.ts

Global Arguments

ArgumentTypeDescription
sshHoststringDocker host running the applied tree (SSH)
sshUserstringSSH username
fn verify(image: string, treePath: string, verifyCommand: string, user: string, pidsLimit: number, memory: string, cpus: string)
Run the host-pinned verify command once to completion in a hardened, network-less, token-less container against the read-only applied tree; return the raw exit code (the green gate).
ArgumentTypeDescription
imagestring
treePathstring
verifyCommandstring
userstring
pidsLimitnumber
memorystring
cpusstring

Resources

result(24h)— The verify run result: { exitCode, stdout }. exitCode is the gate.
@magistr/swamp-go-brr/source-integrationv2026.07.16.2extensions/models/source_integration.ts

Global Arguments

ArgumentTypeDescription
jjPathstringjj binary (PATH-resolved by default)
fn build_workorder(taskId: string, spec: string, writeAllowlist: array, repoScope: string, practices: string, nonce: string)
Read the allowlist's existing files from repoScope (realpath-anchored, DENY-guarded, secret-scrubbed) and assemble the leaf WorkOrder prompt instructing the @@EDIT envelope. No clone — the file slice goes inline; the caller submits with gitRepoUrl=''.
ArgumentTypeDescription
taskIdstring
specstring
writeAllowlistarray
repoScopestring
practicesstring
noncestring
fn apply(repoScope: string, base: string, tasks: array)
Fan-out apply of N completed leaves, each as a PER-TASK ISOLATED jj change off the COMMON BASE (siblings, never stacked) so each task's tree gates in isolation. Parses the @@EDIT envelope, enforces the allowlist/DENY/caps + realpath ACL, writes regular files only, runs the mode-aware re-walk tripwire, and returns per-task Success {changeId, host-observed changedPaths, scrubbed diff, declaredEnvelopeSummary} or Failure {failureKind, note}.
ArgumentTypeDescription
repoScopestring
basestringthe common base change id all task changes branch from
tasksarray

Resources

workorder(24h)— A built leaf WorkOrder prompt (the inline file slice + practices + @@EDIT instructions).
applied(24h)— Per-task apply results: { taskId -> Success {changeId, changedPaths, diff, declaredEnvelopeSummary} | Failure {failureKind, note} } (typed AppliedTaskResult union). changedPaths/diff are HOST-OBSERVED (jj diff), never agent-declared; declaredEnvelopeSummary is AGENT-DECLARED intent (block count, edits-per-file, target paths) recorded for the audit contrast, advisory only.
@magistr/swamp-go-brr/preflightv2026.07.16.2extensions/models/preflight.ts

Global Arguments

ArgumentTypeDescription
registryAddrstringLocal OCI registry for the digest pin
sshUserstringSSH user for the local docker-verify gate
jjPathstring
fcHoststringFirecracker fabric host (fab instance)
snapshotPathstring
memFilePathstring
queueRootstring
vaultNamestring
oauthSecretKeystring
fn pin_image(name: string, tag: string, buildContext?: string, sourceImage?: string)
Ensure the local registry, then digest-pin the codebase's gate image (build its `buildContext`, or pin a prebuilt `sourceImage`) and pull it back for the --network none gate. The toolkit/deps live in that image, not in this model.
ArgumentTypeDescription
namestringImage name to store under in the local registry
tagstring
buildContext?stringPath to a docker build context the codebase owns
sourceImage?stringA prebuilt image ref to pin instead of building
fn config(image: string, verifyCommand: string, gateUser: string, gateCpus: string, gateMemory: string, gatePidsLimit: number)
Emit the run config: pass the codebase-specific digest-pinned `image` and `verifyCommand`; the generic substrate (instances, fabric_up inputs, vault CEL, gate params) comes from globalArgs/defaults.
ArgumentTypeDescription
imagestringDigest-pinned gate image (from pin_image)
verifyCommandstringHost-pinned verify command run inside the gate container
gateUserstring
gateCpusstring
gateMemorystring
gatePidsLimitnumber
fn scaffold(repoPath: string, files: array, describe: string)
Scaffold a greenfield repo for a gobrr run: write the baseline files (caller brings the set — see the deno/swamp-extension preset in references/preflight.md), `jj git init --colocate`, describe the bootstrap change, and return the common base change id the loop branches every task off. jj-only.
ArgumentTypeDescription
repoPathstringAbsolute path of the new repo to scaffold
filesarrayBaseline files (repo-relative path + content): scaffold + model stub + the base.test smoke gate
describestring

Resources

pinned(infinite)— The digest-pinned gate image ref (and whether it was built this run).
config(infinite)— The gobrr run substrate config: digest-pinned image, verifyCommand, gate params, fabric_up inputs, and the swamp model-create commands for si/dv/fab.
scaffold(infinite)— The scaffolded greenfield base: repoScope, the jj common-base change id, and the files written.
@magistr/swamp-go-brr/otlp-exportv2026.07.16.2extensions/models/otlp_export.ts

Global Arguments

ArgumentTypeDescription
endpointstring
tokenstring
payloadResourcestring
fn export_run()
Best-effort POST of the derived OTLP payload (the gobrr `traceOtlp`/`metricsOtlp` resource named by globalArgs.payloadResource) to globalArgs.endpoint with a Bearer token from globalArgs.token (https only). Records a typed exportStatus; never throws/aborts the run. Skips (status=skipped) when no endpoint is configured.

Resources

exportStatus(7d)— Typed result of the last OTLP push {status: ok|skipped|error, endpoint(redacted), reason}. Read via `swamp data get <name> exportStatus --json | jq -r .content.status`. The resolved endpoint URL and token are NEVER stored — only a userinfo/query-stripped host.
04Skills1
swamp-go-brr9 files
05Previous Versions5
2026.06.19.3

2026.06.19.3 — docs: expanded manifest description

Changed

  • Expanded the manifest description with a human-oriented overview (what the loop does + the host-isolation/green-gate guarantee) and a "getting started" pointer. The swamp-club extension page renders the description (not the bundled README), so this is what shows there. Docs-only — no behaviour change.
2026.06.19.2

2026.06.19.2 — maintenance: CI republish

No code change. 2026.06.19.1 was published manually (to work around a temporary registry yank), which collided with the CI publish-on-push for the same version ("version already exists"). This release is cut by CI, with per-version release notes now sourced from this CHANGELOG.

2026.06.19.1

Docs: task-oriented README (current with all 5 models + observability) + JSDoc on all entrypoint exports. Quality 14/14. No behaviour change.

2026.06.18.1

OTLP observability + per-leaf cost/tokens/time: gobrr.emit_otlp (traceOtlp/metricsOtlp), new otlp-export egress model, firecracker outputFormat=json, source-integration extractLeafJson. Lockstep 2026.06.18.1.

Added 2, modified 1 models. Added 1 skills

2026.06.12.1

Merge pull request #12 from umag/feat/swamp-go-brr-package

feat(swamp-go-brr): publish @magistr/swamp-go-brr 2026.06.12.1 (driver-free loop)

06Stats
A
100 / 100
Downloads
3
Archive size
123.6 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License declared1/1earned
  • Verified public repository2/2earned
07Platforms
08Labels