Cybernetic control
for agentic software.

regulator

An agent harness built on Pi, with a typed VSM control plane layered on top of it. It is built against one recurring failure mode of autonomous agents: architectural drift that outruns anyone's ability to review it.

What VSM is, and why it matters here

Stafford Beer's Viable System Model comes out of management cybernetics: it asks what any system (an organism, a company, an autonomous agent) needs structurally to keep operating as its environment keeps generating more variety than it can be made to predict. Beer's answer is five functions plus an independent audit: operations that touch the world (S1), coordination that keeps them from colliding (S2), control that decides what happens next (S3), intelligence that watches the environment and the future (S4), and identity that says what the system is and isn't allowed to become (S5), all checked by a function that never just takes the operators' word for it (S3*).

It matters for an agent harness because the model is not a deterministic component. It changes across versions, has no memory of last quarter's incident, and treats a prompt as advice it can ignore, and under pressure will. A harness that regulates entirely through prompt text has exactly as much regulatory variety as the words in that prompt, which is provably less than the variety of a real codebase, a real filesystem, or real money moving. VSM leaves the model's judgment in place and gives it a boundary it can't talk its way out of.

Six functions, one loop

This is Beer's Viable System Model read as a harness architecture. Command flows down as attenuated instruction (grey), and evidence flows back up as amplified fact (teal). Units act on the domain. S3* audits S3 independently and verifies the domain itself at a revision, never through what S1 reports about it. S4 scans the environment on its own channel, arguing with S3 about now vs. next on S5's terms.

Where each function lives today

Design goals and repository layout

packages/
  protocol/       VSM vocabulary + runtime schemas — messages, trace,
                  effects, profiles, registry, contracts, execution,
                  policy, recovery, audit, obligations, memory
  core/           authority (write preflight), leases, thrash detector,
                  execution store, signal sink, budgets, recovery
                  router, effect journal, audit log, obligation ledger
                  and router, identity + memory stores, definition
                  check, registry check + REGULATORS.md / BOUNDARY.md
  checks/         deterministic S3* checks: host-run verification
                  bound to a revision, the technical verdict
  regulator/      the control plane: the `regulator` CLI, the S3 loop,
                  the stores, the host seam, and the definition —
                  registry (43 records), identity, profiles, policies,
                  workloads, the drift eval suite and its committed
                  reports; OPERATING.md says who runs what
  regulator-pi/   the Pi host: the eleven session extensions, the
                  dispatcher, the S5 write gate, typed proposal /
                  audit-finding / uncertainty tools; `pi install`
  control-room/   read-only page over the `regulator status` read
                  model: definition, instances, the unit inspector

docs/             the documentation site (concepts, guides,
                  reference), DEBT.md, decisions/, research/
vsm/               committed S5 artifacts for this repo itself
the course, Viable Agents, lives in its own repository and cites these by link

In the docs: The control plane · Definition, instance, domain · Architecture · Packages

Prefer the mechanism that survives adversarial pressure

When adding a feature to the harness, regulator walks this ladder from the top down: reach for the highest level that can actually do the job, and only fall further down when it can't. If you can write the check, don't write the paragraph.

In the docs: The control plane · Where each rule is enforced · Regulators · Enforcement boundary

Identity you can't prompt away

What the system is (its invariants, its boundaries, the words it uses) lives in four committed files under regulator/identity/. Every unit sees them, rendered from the files on every run, so compaction can't drop them and a new model can't reinterpret them from memory. Seeing them is only advice, though, and a unit with a shell can reach the files. So identity is held the way the mechanism hierarchy says to hold anything that matters: in layers, each catching what gets past the one before.

Changing identity is a separate path, on purpose. A unit may propose a change; the tool records the request and changes nothing. A person the interaction policy lets act as S5 accepts it, as the only writer of an identity file, and may then promote it into the definition, so every later instance starts from it. The right to ask and the right to change are different mechanisms.

Secrets are watched the same way. When regulator init installs an instance, it records the credential-looking values in the repository's committed .env as canaries. Every tool result is scanned for them before the model sees it: a canary is redacted and recorded as a critical finding. A canary the model writes itself can't be unsaid, so that is recorded too. It measures whether an exposure path exists. It only knows the values it was told about, and it doesn't watch the network.

In the docs: Protecting identity · The canary watch · Enforcement boundary

A small loop, purpose-built for regulation

The orchestrator is nothing but the S3 loop (contract → dispatch → verify → route → close), generic over workloads, with leases, budgets and attempts as immutable records. It was built directly on bare Pi, one module per lesson: gates, effects, profiles, leases, contracts, budgets, recovery, audit and authority, with no workflow engine underneath it. The Pi-specific half lives in its own package, regulator-pi, behind a host seam: the control plane never imports a host, it resolves one by name. Workload-specific concerns stay out of the loop entirely and are declared in a workload definition instead, which is what keeps the loop itself small enough to read in one sitting. How a unit runs through the loop is drawn out on its own page.

In the docs: Running units · Work contracts · Host checks · Recovery, budgets and model routes · Coordination · Hosts

Every gate is a claim. The eval harness is how the claim gets tested.

A suite declares the fixture, the tasks in order, the arms, the repetitions and the metrics it will report — before it runs. The control arm loads the plain harness; the treatment arm loads everything the workload declares; one ablation arm per regulator switches that one regulator off. The harness runs one fresh instance per arm and repetition through the real loop and grades every unit the same two ways.

Pre-registered, and interpreted by a person. The metrics are a closed list named in the suite, so a run cannot discover a favourable one afterwards. Arms are summarized with Student's t intervals and a lift is screened by interval overlap, never a p-value. And a report is not a report until someone says what it means: regulator eval without --interpretation writes a placeholder, and regulator check refuses a committed report that still carries it. The four committed reports ran scripted units — their numbers validate the graders, not a model — and one of them is the over-regulation case that changed the product: a check refused correct work over a word in a commit message, and the workload now declares that half advisory.

In the docs: Evidence about the regulators · Eval suites

What is outside and later is not what was learned here

Two things look alike from a prompt and are kept apart on purpose. S4 is the environment and the future: a research unit, under its own read-only profile and budget, reports what it found with report_intelligence, and the signal becomes an obligation that holds the units it names until S3 or a person dispositions it. Intelligence can stop work; it never replans on its own.

Memory is operational, and it expires. A unit that learns something about this environment — a flag the tests need, a command that only works one way — records it with remember. The fact carries its provenance (the unit, the revision), a review-by date that cannot be more than ninety days out, and optionally the unit types it is for. Later units see current facts rendered as facts, scoped to their type; an expired fact is shown to nobody until a person reviews it. Nothing checks that a fact is true — the expiry is the pressure.

Neither is a rule. A fact that turns out to be a rule, or a finding that should change what the system is, goes through propose_policy_change and waits for the S5 decision. Memory never becomes identity by being repeated, and the drift suite measures the difference: rules written into a README count against a unit; facts recorded with an expiry do not.

In the docs: Intelligence and memory · Session tools

Anatomy of a registry card

Every regulator in the control plane has a record, and the definition check refuses a gate that does not state what it fails to catch. The cards are the source of truth for what the system does and does not do; REGULATORS.md and the enforcement boundary, BOUNDARY.md, are rendered from them and never edited by hand.

Retirement is a decision, and the record stays. Two of the forty-four cards are retired: the first lexical write gate, superseded by the identity write gate, and the post-merge check, replaced by the pre-merge trial. Each keeps its history and says what replaced it, so the registry reads as the system's memory of itself, not only its present.

In the docs: The regulators · Enforcement boundary · Build debt

The control room

A projection of registry ∪ execution store ∪ regulatory state. It owns no state of its own: every screen is read from records that already exist elsewhere. packages/control-room serves this page today, over the read model built by regulator status.

More of the page (units, leases and obligations for a live instance, the assurance and lifecycle views, a unit's full replay) is on the worked example and how it works.

In the docs: The control room · Evidence about the regulators

Install into a repository you already have

Two packages, then one command to declare the instance, one to check it, and one to run a unit. You need Node 22.19 or later and Pi 0.87.0 with a model provider key in its environment.

pnpm add -D @metacoding.io/regulator @metacoding.io/regulator-pi
cd /path/to/your/repo                         # clean tree, on the branch units should land on
regulator init --writable src/,test/ --protected vendor/ --by alice
regulator doctor                              # the CI entry point: exit 1 on any problem
regulator unit drive contracts/my-first-unit.json
regulator unit show u1 · unit evidence u1 · obligations

init seeds the identity under regulator/identity/, writes the instance manifest, and commits. drive leases the unit, opens a session under the unit type's profile, runs the host checks at the unit's revision, and either closes and reintegrates or routes the failure under the recovery policy. What the policy cannot resolve becomes an obligation owed to you.

In the docs: Getting started · Declare who may answer · CLI reference · npm ↗

What a person does day to day

The loop runs units, and a person answers what the loop cannot decide. Everything below reads or dispositions a record, and every --by is checked against the interaction policy's people before anything is written.

In the docs: Running units · Obligations · Asking a person · Operating · The control room · Session tools

Built end to end through lesson 15; the capstone is what's left

Four things are true today, and each runs end to end.

docs/DEBT.md tracks every gap the build has taken on deliberately, one row per item: forty-one rows so far, most already paid as later lessons closed them. What's still open, and worth knowing before you rely on this:

In the docs: Build debt · Roadmap · Changelog