Skip to content
loopexec loopexec loopexec

loopexec

Documentation source v0.4.1. Published releases

CI Latest tag License: MIT Go version

loopexec is a deterministic runtime for loop engineering: it drives bounded, stateless, auditable execution loops that progress through an external check and stop on a computed reason, never on an agent’s say-so. It is the runtime companion to SMALL Protocol: SMALL describes state, constraints, plans, progress, and handoff; loopexec drives one bounded loop against that state and reports machine-readable outcomes.

The normative contract is SPEC.md. The current source implements bounded execution, determinism probing, integrity and regression guards, offline-verifiable receipts, and opt-in unattended workflows. See SPEC.md section 11 for the implemented scope and remaining sub-parts.

Current status

Source identity: v0.4.1. This patch adds evidence-complete reports and enforced code/docs release continuity. See v0.4.1 notes; the Releases page establishes publication status. Workflow thresholds remain supplied by each integration.

Implemented through v0.4.0:

  • Real bounded run loop: iterates --exec then --check until the check passes (success_condition_met), a bound trips (max_iterations_reached), or work fails (execution_failure); “no check, no loop”; computed halt reasons mapped to a stable exit-code class; typed JSONL receipts (.loopexec/run-<id>.jsonl) and atomic durable state.

  • probe-check - determinism as a 95% confidence bound (rule of three); doctor - precondition gate (determinism + isolation preflight).

  • Set-based progress + no-regression ratchet (oscillation / no-progress / regression halts) + explain-halt (raise-the-limit vs do-not-retry).

  • Metric-integrity gate (run --integrity-cmd): guards dominate success (collected-set monotonicity).

  • Receipt pinning (model tuple + sampling + context manifest + cost + check fingerprint); replay (verify a receipt offline, agent-free) and attest (HMAC-sign + verify).

  • reexecute (live re-run distribution), escalate / watch (heartbeat + structured packet), comprehension ack gate.

  • build-context - budgeted, workdir-confined, symlink-safe relevant-file slice.

  • Shared subprocess deadlines/cancellation with bounded diagnostics; fail-closed collectors.

  • run --workflow: exact usage/reservations, explicit strict/observed/unknown money, numeric progress/patience, and manifest-based best-candidate restoration.

  • An offline Go creative-workflow adapter with independent simulated roles and candidate-bound signed reviews. No Python loop, model key, network, or engine required.

  • Opt-in shared model-call budgets across run IDs, with pinned per-phase allowances and durable pre-call reservations. See the offline adapter proof.

  • isolate - two-zone orchestration: detached-clone sandbox + per-run minted/revoked credential + rendered/launched exec/agent zones.

  • Global --json output, explicit exit-code contract, contract and unit tests, GitHub Actions CI (gofmt, go vet, go test ./...).

Not implemented yet (named sub-parts; see SPEC.md section 11):

  • The operator-provided infra isolate composes with: the container engine, the auditing egress proxy, and the provider key API (--runtime / --egress-proxy / --mint-cmd + --revoke-cmd).
  • Provider-specific live usage wrappers; the deeper metric-integrity layers (assertion-count / coverage-floor); probe-check adversarial perturbation + the in-loop sequential monitor.
  • The import_closure / dep_graph context-relevance tiers; github/slack escalation channels; the kill-the-PID watchdog actuator.
  • Full SMALL-driven task_list loop execution and small CLI integration; container, Nix, or remote substrates and multi-worker orchestration.

Install

Terminal window
go install github.com/justyn-clark/loopexec/cmd/loopexec@latest

Requires Go 1.26 or newer. For a pinned v0.4.1 install, use @v0.4.1 once that release is published. Until then, v0.4.0 remains the prior published stable release. Prebuilt archives and SHA256 checksums are linked from GitHub Releases.

loopexec --version prints the installed version; loopexec version --json emits its machine-readable identity. See the release notes for compatibility and platform limits.

SMALL is optional for LoopExec consumers. This repository uses the tracked .small/ files for its own development audit; CI requires a canonical progress update with source or documentation changes and validates the tracked state. The SMALL integration guide covers SMALL CLI v1.1.0 with legacy v1 artifacts and opt-in collaborative v2 sessions; LoopExec remains the loop governor.

60-second proof

Run the built-in deterministic demo with no API key, model, or network dependency:

Terminal window
loopexec demo

The command creates a red local fixture, sends it through the real bounded loop, repairs it, observes the external check turn green, writes a typed JSONL receipt, and verifies the recorded check fingerprint through the same verifier used by loopexec replay. It proves LoopExec’s execution-integrity contract; it does not run an agent.

The receipt path in the output identifies the retained temporary workdir. To keep the proof at a known path, pass a fresh directory with --workdir <dir>; demo refuses to overwrite an existing .loopexec directory or status.txt fixture.

Build

From the repo root:

Terminal window
go build ./cmd/loopexec

Test

Terminal window
go test ./...

CI enforces:

  • gofmt
  • go vet ./...
  • go test ./...

Code/tooling changes also require canonical documentation and changelog updates. The generated CLI and JSON contract is checked against the runtime. Every release packages source-bound docs and publication requires matching deployed content. See continuity policy for enforcement and the pending website rollout boundary.

CLI

The implemented CLI returns deterministic human or JSON output.

Commands

  • loopexec init / demo / run / status / check / step
  • loopexec probe-check / doctor / explain-halt
  • loopexec replay / attest / report / reexecute
  • loopexec escalate / watch / ack
  • loopexec build-context / isolate / inspect-cost
  • loopexec budget status / budget reserve for cross-run child-call limits

See docs/cli.md for flags and exit semantics. The opt-in scoped budget reserves a child model call before an adapter launches it; changing the run ID does not reset the allowance. It counts calls, not tokens or dollars.

See acceptance and evidence for general-purpose objective, retention, convergence and owner-decision boundaries. The creative verification guide is an optional example. The status and roadmap distinguishes published capabilities, local improvements, and remaining work.

Global flag

  • --json - emit exactly one JSON object to stdout

Example

Terminal window
loopexec init
# A real bounded loop: run the work command, then the check, until green or a bound trips.
loopexec run --json --check "go test ./..." --exec "make fix" --max-iterations 10
loopexec status --run-id local --iteration 1
loopexec check

Example JSON response (a converged run):

{
  "tool": "loopexec",
  "version": "0.4.0",
  "status": "halted",
  "run_id": "local",
  "iteration": 3,
  "halt_reason": "success_condition_met",
  "check_exit": 0,
  "receipt": ".loopexec/run-local.jsonl",
  "errors": []
}

Exit codes

The halt_reason string is the stable contract; the exit code is its coarse class (SPEC section 5). Every class 13-19 emits today alongside the base 0/10/12/20/30/40/50 (class 18, budget_exceeded / cost_anomaly, via inspect-cost and workflow runs; class 15, check_inadequate, via the doctor --mutate-cmd adequacy canary); only class 11’s task-list reasons (no_actionable_tasks / human_required) remain reserved, and those belong to the task_list loop topology. A few individual reasons inside active classes, the doctor coverage-delta and hermeticity tiers, are still Planned (see SPEC section 11).

  • 0 success (loop ran, no halt)
  • 10 converged: success_condition_met
  • 11 terminal-blocked: no_actionable_tasks, human_required
  • 12 iteration-cap: max_iterations_reached
  • 13 integrity: blocked_path_modified, reward_hacking_detected, metric_integrity_violation
  • 14 oracle-untrusted: check_flaky, check_not_hermetic, hermeticity_violation
  • 15 check-inadequate: check_inadequate
  • 16 resumable-judgment: escalation_pending, reviewer_rejected
  • 17 no-convergence: no_progress_detected, oscillation_detected, infeasible_suspected
  • 18 budget: budget_exceeded, cost_anomaly
  • 19 liveness/drift: heartbeat_stale, model_drift_detected, comprehension_debt_exceeded
  • 20 invariant failed
  • 30 workspace invalid or missing
  • 40 execution failure
  • 50 internal error

Repository layout

SPEC.md                   canonical, normative contract (source of truth)
cmd/loopexec/             loopexec CLI
docs/architecture.md      planned loop architecture
docs/cli.md               current loopexec command contract
docs/integrations.md      integration guidance for the implemented CLI
docs/loop-contract.md     task_list mode profile of SPEC.md
.github/workflows/ci.yml  fmt/vet/test CI gate
scripts/feeltest.sh       deterministic shell feel test helper

SMALL relationship

This repo is SMALL-governed at the repository level. The implemented loopexec binary runs the check_fixpoint loop standalone; the full SMALL-driven task_list loop is the profile described in docs/loop-contract.md.

Read the docs in this order:

  1. SPEC.md - the canonical, normative contract (source of truth for the binary and the docs site)
  2. docs/cli.md - what the current CLI actually does
  3. docs/integrations.md - how to integrate with the current implementation
  4. docs/architecture.md - target architecture and planned boundaries
  5. docs/loop-contract.md - the task_list mode profile

License

MIT. See LICENSE.

Offline creative workflow

Terminal window
mkdir -p build
go build -o build/loopexec ./cmd/loopexec
go build -o build/creative-workflow ./examples/creative-workflow
./scripts/creative-proof.sh ./build/loopexec ./build/creative-workflow build/creative-proof

The proof asserts convergence, budget stop before further work, regression restoration, stale-evidence rejection, critic skip after technical failure, and a four-attempt cap. Expected convergence is loopexec exit 10 (external check exit 0). All fixture scores, captures, and charges are synthetic; they prove runtime wiring. Read the workflow contract for interfaces, receipts, trust boundaries, and live setup. Migration: a nonzero --budget-usd now requires explicit workflow metering; legacy set-based progress remains the default.