Architecture

This page describes the architecture as the contract specifies it. As of v0.2.0 the binary ships the engine; where a named sub-part below is not yet shipped, it is framed as the spec, and the capability status table marks what is real. Read this as both the shape the runtime enforces and the contract it is held to.

Three protocols, one discipline

loopexec is one layer of the JCN stack - a small family of protocols that together make unattended work durable, governed, and auditable. The stack takes one hard problem - can a human trust the output of a loop that ran while they slept? - and splits it into three questions, giving each question to exactly one owner.

Layer	Owns the question	The answer is
LoopExec	Did the external check pass?	a number - exit code, fingerprint, halt reason
Musketeer	Should a human trust it?	a judgment - a verdict
SMALL	What is true on disk, and can we resume it?	durable state

LoopExec runs the loop. Musketeer governs the roles. SMALL preserves the state. The boundaries are not stylistic. They fall exactly along the line between what a number can decide and what it cannot.

The split

LoopExec - the deterministic runtime. It runs bounded, stateless, auditable work loops. A loop runs until an external check passes, a guard trips, a budget is spent, or a human is required - never because an agent reports it is done. LoopExec hosts two topologies, recorded in every receipt: check_fixpoint (iterate until an external oracle returns its success_exit_code) and task_list (iterate a SMALL plan until every task is completed). check_fixpoint is the degenerate one-task plan whose acceptance criterion is the external check. See Loop engineering.

Musketeer - role governance. It governs the four roles around the loop: planning, challenge, execution, and review. It answers the question a number cannot - should a human trust this diff? - and emits a verdict. The verdict is advisory and it is one-directional: it can veto a green loop or escalate, but it can never promote a red one. Judgment is never the stop oracle.

SMALL - the state protocol. It preserves what is true on disk so a loop is resumable and audited rather than remembered. In task_list mode the stop condition is all SMALL plan tasks completed, gated by small check --strict plus a per-task acceptance oracle. State hygiene alone is not an acceptance oracle - it cannot decide application correctness - so a task_list loop without a real per-task oracle MUST refuse to mark tasks completed and halt check_inadequate.

The ownership boundary

The division is explicit and load-bearing. It is the reason the loop is auditable offline.

LoopExec owns everything a number can decide - exit codes, the failing-test set trajectory, a fingerprint hash, a coverage and mutation delta, a manifest hash, a spend ledger, a model-identity tuple, a sequential flake bound. Musketeer owns only what a number cannot express - reward_hacking_detected, reviewer_rejected - layered on top of the deterministic metric_integrity_violation, never replacing it. Humans own the irreducible decision and the ack. Judgment is never the stop oracle: it can veto a green loop or escalate, but it cannot promote a red one to green.

This is why guards dominate success. Guards are evaluated against the immutable baseline t0 before any green branch can fire. A check that went green because a guard was violated - a weakened test, a shrunk collected set - classifies as the guard reason, not success_condition_met. The deterministic gate runs first; the judgment layer sits above it and can only subtract trust, never add it. See Halt reasons.

The unowned question: check adequacy

A clean split is tempting: LoopExec decides did-the-check-pass, Musketeer decides should-a-human-trust-it. That split has a hole, and the hole is the most dangerous failure in the whole system.

Ask: does the check actually exercise the changed code? A check that returns 0 regardless of the diff is perfectly deterministic and perfectly useless. Determinism is not adequacy. The naive split leaves adequacy owned by neither layer - LoopExec only confirmed the check is stable, Musketeer was never handed the question - and the loop goes green on code the check never ran. This is the false fixpoint.

The resolution is a boundary call, not a new role. Adequacy is computable: a coverage delta proves every changed or added line is exercised, and a mutation canary injected into changed lines MUST turn the check red. Because it reduces to a number, it belongs to LoopExec, not Musketeer - specifically to doctor, the precondition gate. The contract assigns adequacy to doctor; failure halts check_inadequate. Adequacy is a question of fact, so it is never delegated to judgment.

Capability honesty

doctor ships its determinism and isolation preflight (SPEC section 11), and now also ships the mutation-canary adequacy gate (doctor --mutate-cmd, which plants a mutation in an isolated copy of the workdir and halts check_inadequate when the --check stays green); the coverage-delta tier of adequacy and hermeticity remain Planned. loopexec is specified to refuse a loop whose check does not exercise the changed code; the mutation-canary half of that enforcement ships today, while the coverage-delta tier does not yet. The architecture below is the contract; the status table marks what ships today.

The layering

The stack reads bottom-up: SMALL is the ground truth on disk, LoopExec is the runtime that drives the loop against it, Musketeer governs from above, and the human sits at the top with the only authority that cannot be computed.

        +--------------------------------------------------+
        |                      HUMAN                        |
        |   owns the irreducible decision and the ack       |
        +-------------------------+------------------------+
                                  | escalate ^   /   ack v
        +-------------------------+------------------------+
        |                    MUSKETEER                      |
        |   role governance: plan | challenge | execute |   |
        |   review                                          |
        |   asks: should a human trust this?                |
        |   verdict may VETO a green loop - never promote   |
        |   a red one                                       |
        +-------------------------+------------------------+
                                  | advisory verdict, ON TOP OF the gate
        +-------------------------+------------------------+
        |                     LOOPEXEC                      |
        |   the deterministic runtime                       |
        |   asks: did the external check pass?              |
        |   computes the halt reason | owns ADEQUACY        |
        |   (doctor) | guards dominate success |            |
        |   emits the replayable verdict                    |
        +-------------------------+------------------------+
                                  | durable state + signed receipts
        +-------------------------+------------------------+
        |                       SMALL                       |
        |   state protocol: what is true on disk,           |
        |   and how the loop resumes it                     |
        +--------------------------------------------------+

Each arrow is a typed contract, not a conversation. Musketeer’s verdict layers onto LoopExec’s gate; it does not bypass it. The human’s ack and escalation are signed events, not chat. SMALL’s state is read from disk, never from memory.

Inside LoopExec: the two zones

LoopExec’s own runtime is itself split, because a single --network none container cannot both run a cloud agent and isolate untrusted code. The contract specifies two-zone isolation: an agent zone and an exec zone sharing only a work volume that is a detached clone - a git worktree is ergonomic, not a security boundary, because it shares the object DB, refs, remotes, hooks, and credentials.

        +-----------------------------------------------+
        |            loopexec runtime (host)            |
        |  orchestrator | receipts | heartbeat |        |
        |  mints + revokes creds | doctor | watchdog    |
        +-------+---------------------------+-----------+
                v                           v
   +-------------------------+  +--------------------------+
   |       AGENT ZONE        |  |        EXEC ZONE         |
   |  reasoning / produce    |  |  check | build | test    |
   |  diff                   |  |  untrusted: CODE exec     |
   |  untrusted: prompt input|  |  net: NONE                |
   |  net: EGRESS ALLOWLIST  |  |  hermetic: frozen clock/  |
   |   -> model endpoint only |  |   seed/TZ/locale, :0 ports|
   |  creds: per-run minted, |  |  creds: NONE             |
   |   short-TTL, spend-cap  |  |  ephemeral: reset per run |
   |  NO $HOME | NO ~/.claude |  |                          |
   +-----------+-------------+  +------------+-------------+
               +--------------+---------------+
              shared /work ONLY - a detached CLONE, not the host repo

The agent zone reaches exactly one endpoint through an auditing proxy, so even a stolen key drops everywhere except the model API. The exec zone runs untrusted code with no network at all. This is the same ownership principle one level down: the reasoning surface and the execution surface are different threats, so they get different boundaries. Two-zone isolation via isolate, the per-run minted key, and the metric-integrity gate are Shipped (core) (SPEC section 11) - the detached-clone orchestration, the minted/revoked credential, and collected-set monotonicity ship, while the container engine, the auditing egress proxy, the provider key API, and the deeper assertion-count / manifest-hash / coverage-floor layers are operator-provided hooks or Planned. The contract requires the gate fail closed before the loop runs unattended on a credentialed repo. See Isolation.

Replayable verdicts, not replayable runs

The architecture makes a precise, narrow promise. A live-LLM trajectory is not reproducible - the model samples, drifts, and tools are nondeterministic. Only the verdict is verifiable. So the contract separates two verbs that must never blur: replay re-runs the deterministic check against the recorded end-state and confirms the fingerprint matches the receipt (agent-free, budget-free), while reexecute runs the live loop again and reports a statistical match. Marketing copy says replayable verdicts, never “replayable runs.” Determinism itself is held as a maintained confidence bound on the check’s flake rate, not a one-time probe. See Determinism.

Ecosystem siblings

The other JCN-stack protocols are documented on their own sites. The claims here are deliberately high-level; each project is the authority on itself.

• musketeer.dev - Musketeer, the role-governance layer. It coordinates the planning, challenge, execution, and review roles and produces the verdict that answers should a human trust this? It sits above LoopExec and never replaces the deterministic gate.
• smallprotocol.dev - SMALL, the state protocol for governed repositories. It keeps durable, resumable, audited state on disk and provides the task_list gate (small check --strict).
• toolbus.dev - toolbus, the tool-access layer that brokers how work reaches tools and capabilities.

These are separate projects in one ecosystem. loopexec composes with them; it does not depend on them to run a check_fixpoint loop standalone.

Capability status

This page describes the architecture the binary ships as of v0.2.0. The normative source for what ships is SPEC section 11. The relevant rows:

Capability	Status
CLI contract: --json, stable exit codes, deterministic output	Shipped
init / status / check / step commands	Shipped
run as a real iterating loop	Shipped
Computed halt reasons replacing --halt-reason	Shipped
Typed JSONL receipt + durable state	Shipped
probe-check confidence bound	Shipped (core)
doctor precondition gate (isolation + adequacy canary shipped; coverage-delta + hermeticity Planned)	Shipped (core)
Two-zone isolation + per-run minted key	Shipped (core)
Metric-integrity gate	Shipped (core)
replay / reexecute, attest / ack	Shipped

Note

When a capability moves status, SPEC section 11 changes first. The binary’s tests and this page both reference it. If this table and the spec ever disagree, the spec wins.