loopexec

A loop should not run because an agent feels done. It runs until an external check passes, a guard trips, a budget is spent, or a human is required. Every halt emits a computed reason and a replayable receipt.

Why loop engineering

loopexec is specified by one normative contract. These are its load-bearing properties.

• Deterministic checks - the stop oracle is an external process returning an exit code, never the agent’s self-assessment. Determinism is a maintained confidence bound, not a one-time probe.
• Stateless iterations - progress lives on disk and in git, not in the context window. Each iteration rebuilds a narrow, budgeted slice, so cost stays roughly linear instead of quadratic.
• Guards dominate success - guards are evaluated before any green branch can fire. A check that went green because a guard was weakened halts as the guard reason, not success_condition_met.
• Two-zone isolation - an agent zone (model egress only) and an exec zone (--network none) share one detached clone. A git worktree is ergonomic, not a security boundary.
• Reward-hacking gates - the metric-integrity gate freezes the test-determining surface at t0: collected-test-set monotonicity, assertion counts, a protected-manifest hash. You cannot pass by testing less.
• JSONL receipts - every iteration appends a typed JSONL event pinning the model-identity tuple, sampling params, context manifest, and cost actuals - or it fails closed.
• Replayable verdicts - replay re-runs the deterministic check against the recorded end-state, agent-free and budget-free. A live trajectory is not reproducible; the verdict is.
• Stable halt reasons - every halt reason is computed from observed state, never a flag. The string is the integration contract; the exit code is a coarse class CI can branch on.
• SMALL-compatible state - durable, resumable .loop_state.json that composes with SMALL-governed repositories without requiring one.

The lane

LoopExec runs the loop | Musketeer governs the roles | SMALL preserves the state.

loopexec is not an agent, a model, or a task runner. It composes with those by governing how work is executed, recorded, and resumed.

What ships today

As of v0.2.0 the loopexec engine is complete through Slice 7. The CLI contract - --json output, stable exit codes, deterministic output - ships now, and so do the loop mechanics above: run is a real iterating loop that runs your exec then your check each iteration, computes its own halt reason, and writes a typed JSONL receipt plus durable, resumable state. Every command ships; what stays Planned is named sub-parts of the shipped cores (live/auto cost metering, deeper integrity and probe layers, the operator-provided isolation hooks). See Capabilities for the per-capability Shipped / Shipped (core) / Planned status. Nothing Planned is presented here as if it ships today.