Swamp Go Brr
@magistr/swamp-go-brrv2026.08.19.1
Security Notice
This extension includes AI agent skills that can modify AI assistant behavior. Review the skill files before installing.
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) andapply(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_imagebuilds a build context or pins a prebuilt ref — the toolkit/deps live in that image, not here), and emits the runconfig(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 derivedtraceOtlp/metricsOtlpto a configurable OTLP/HTTP collector (https), endpoint + token from a vault CEL, best-effort. gobrr'semit_otlpderives the OTLP span tree + per-leaf token/cost/time metrics; leaves run withoutputFormat=jsonso claude's usage rides back. Each leaf runsclaude --printin 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.
02Models
@magistr/swamp-go-brr/gobrrv2026.08.19.1extensions/models/gobrr.ts
fn start(intake: string)
Start a run: record the human intake + the host-pinned RunConfig (verifyCommand, verifyInputs, repoScope, caps).
| Argument | Type | Description |
|---|---|---|
| intake | string |
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.
| Argument | Type | Description |
|---|---|---|
| tasks | array |
fn next(owner: string)
Lease the next ready task to `owner` (or report all-green / halt). Reaps expired leases, propagates blocked, enforces caps.
| Argument | Type | Description |
|---|---|---|
| owner | string |
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.
| Argument | Type | Description |
|---|---|---|
| taskId | string | |
| owner | string | |
| verifyExitCode | number | |
| 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).
| Argument | Type | Description |
|---|---|---|
| parentId | string | |
| owner | string | |
| spec | string | |
| writeAllowlist | array |
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).
| Argument | Type | Description |
|---|---|---|
| taskId | string | |
| owner | string | |
| 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.
| Argument | Type | Description |
|---|---|---|
| reason | string |
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.08.19.1extensions/models/docker_verify.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| sshHost | string | Docker host running the applied tree (SSH) |
| sshUser | string | SSH username |
| verifyTimeoutMs | number | Client-side wall-clock budget (ms) for the whole ssh verify invocation (handshake + remote docker run). On expiry the ssh child is killed and exitCode=124 is recorded (fail-closed) — ssh's own ConnectTimeout bounds only the handshake. |
| sshKnownHostsFile? | string | Override ssh's UserKnownHostsFile. Defaults to /dev/null only when sshStrictHostKeyChecking=\ |
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).
| Argument | Type | Description |
|---|---|---|
| image | string | |
| treePath | string | |
| verifyCommand | string | |
| user | string | |
| pidsLimit | number | |
| memory | string | |
| cpus | string |
Resources
result(24h)— The verify run result: { exitCode, stdout }. exitCode is the gate.
@magistr/swamp-go-brr/source-integrationv2026.08.19.1extensions/models/source_integration.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| jjPath | string | jj binary (PATH-resolved by default) |
| jjTimeoutMs | number | Client-side wall-clock budget (ms) for each local jj invocation (new/diff/log). On expiry the jj child is killed and that call is treated as a transport failure (synthetic exit 124). |
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=''.
| Argument | Type | Description |
|---|---|---|
| taskId | string | |
| spec | string | |
| writeAllowlist | array | |
| repoScope | string | |
| practices | string | |
| nonce | string |
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}.
| Argument | Type | Description |
|---|---|---|
| repoScope | string | |
| base | string | the common base change id all task changes branch from |
| tasks | array |
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.08.19.1extensions/models/preflight.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| registryAddr | string | Local OCI registry for the digest pin |
| sshUser | string | SSH user for the local docker-verify gate |
| jjPath | string | |
| fcHost | string | Firecracker fabric host (fab instance) |
| snapshotPath | string | |
| memFilePath | string | |
| queueRoot | string | |
| vaultName | string | |
| oauthSecretKey | string |
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.
| Argument | Type | Description |
|---|---|---|
| name | string | Image name to store under in the local registry |
| tag | string | |
| buildContext? | string | Path to a docker build context the codebase owns |
| sourceImage? | string | A 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.
| Argument | Type | Description |
|---|---|---|
| image | string | Digest-pinned gate image (from pin_image) |
| verifyCommand | string | Host-pinned verify command run inside the gate container |
| gateUser | string | |
| gateCpus | string | |
| gateMemory | string | |
| gatePidsLimit | number |
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.
| Argument | Type | Description |
|---|---|---|
| repoPath | string | Absolute path of the new repo to scaffold |
| files | array | Baseline files (repo-relative path + content): scaffold + model stub + the base.test smoke gate |
| describe | string |
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.08.19.1extensions/models/otlp_export.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| endpoint | string | |
| token | string | |
| payloadResource | string |
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.
03Skills
swamp-go-brr9 files
04Previous Versions
2026.08.07.1
2026.08.07.1 — privacy: neutral defaults for sshUser/jjPath/fcHost
preflight's GlobalArgs defaulted three fields to this homelab's REAL
infrastructure: sshUser to the operator's actual local unix username, jjPath
to that user's actual home-directory path, and fcHost to the operator's actual
Firecracker fabric hostname. Any installer who created a preflight instance
without overriding these globals inherited that disclosure verbatim (surfaced in
instanceCommands' generated swamp model create strings). All five models
bump to 2026.08.07.1 (lockstep, single manifest version); only preflight
changes functionally.
Fixed
preflight'sGlobalArgs.sshUserdefault (the operator's real local unix username) →runner(a generic agent/CI-style username, matches no real account).preflight'sGlobalArgs.jjPathdefault (an absolute path under that same real user's home directory) →jj(PATH-relative — matchessource-integration's ownjjPathdefault, which was already neutral).preflight'sGlobalArgs.fcHostdefault (the operator's real Firecracker fabric hostname) →firecracker.example.com(RFC 2606 reserved example domain).- Behavior-preserving for every instance that already sets these globals
explicitly (the overwhelming majority — the defaults only matter for a
brand-new instance created with no
--global-argoverrides). No resource schema change;upgradeAttributesis identity on all five models.
Changed
preflight.test.ts'sSUBfixture and theinstanceCommandsexpected command strings updated to the new neutral defaults.- Five
// Run: …dev-comment header lines across the test suite (gobrr.test.ts,gobrr_observability.test.ts,lib/otlp.test.ts,otlp_export.test.ts,source_integration_leaf_json.test.ts) that hardcoded the same real absolute home-directory path in an exampledeno testinvocation now use~/.swamp/deno/deno(matches the convention already used byreading-list/README.md). Comment-only, no behavior change.
2026.07.16.2
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.
Added 5, removed 1 models. Added 1 skills
2026.06.19.3
2026.06.19.3 — docs: expanded manifest description
Changed
- Expanded the manifest
descriptionwith 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 thedescription(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)
05Stats
A
100 / 100
Downloads
3
Archive size
142.2 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
Repository
https://github.com/umag/swamp-workspace06Platforms
07Labels