Token-Efficient Agent Harness Lab
Evidence and safety infrastructure for coding-agent repository workflows.
Prove that agent-generated patches, reviews, and CI results belong to the exact commit being shipped — with budgets, audit, recovery, and a local operator dashboard that fails closed instead of inventing success.
The failure this prevents
A green CI check is not enough if it belongs to an older PR head. This lab binds dispatch, CI, review, and merge evidence to an exact commit and rejects stale identity.
What the full control plane adds
- Deterministic budget evidence and regression scorecards
- Audited dispatch, pause, recovery, and operator decisions
- Bounded adaptive routing behind explicit fail-closed gates
- Supervised repository patch/PR output (never silent target-
main writes)
- Local dashboard that refuses invented success
Boundary: local / small-team research tool — not multi-tenant SaaS, not a free provider proxy, no container/VM isolation claim. Provider, managed-CLI, adaptive, and autonomous paths remain default-off and use explicit fail-closed authority, identity, budget, lease, audit, and kill controls. Governance and testing rules are owned by docs/AUTONOMY.md; the roadmap is in docs/ROADMAP.md.
The engineering mainline is the autonomous development and maintenance loop:
start from START_HERE.md, inspect the repository and live PR/CI state, make
the requested change, verify it, obtain exact-head review, pass canonical CI,
and confirm the guarded merge. Research programs are separate optional work,
not an entry gate or substitute for repository maintenance. See
docs/ROADMAP.md for priorities.
Maintainer and Agent entry: START_HERE.md · architecture: docs/ARCHITECTURE.md · autonomy & testing: docs/AUTONOMY.md · roadmap: docs/ROADMAP.md · implementation rules: AGENTS.md · support: SUPPORT.md.
Quick Start
Verified on a source checkout with Rust stable, Bun, and uv (Python 3.11+ for the SDK; 3.10+ scripts where noted). See CONTRIBUTING.md.
Usable local harness (CLI + Linux desktop)
One entry starts the operator UI and the companion CLI jobs. No API key and no model call for these paths:
git clone https://github.com/Igzela/token-efficient-agent-harness-lab.git
cd token-efficient-agent-harness-lab
./scripts/harness.sh start # engine + dashboard UI (opens browser)
./scripts/harness.sh work # finish one real local-folder job
./scripts/harness.sh self-test # full provider-free function + perf matrix
./scripts/harness.sh install-desktop # Linux app-menu launcher
./scripts/harness.sh stop
| Command | What you get |
|---|
./scripts/harness.sh start | Loopback engine + full dashboard (Mission Control, Operator, Runs, Scheduler, Settings, Health, Audit) |
./scripts/harness.sh work | One checked file written under .acp-work-state/inbox/ |
./scripts/harness.sh demo | No-provider evidence / stale-head proof |
./scripts/harness.sh doctor | Toolchain + optional auth + live self-test gate presence (fixture path OK on WARN) |
./scripts/harness.sh bootstrap-auth | Optional local admin key for protected/dashboard/provider paths |
./scripts/harness.sh self-test | Pure checks + doctor + local-work golden path + efficiency fixture scorecard (PASS required); live model/perf when ACP_SELF_TEST_LIVE_CONFIRM and credential env are set |
./scripts/harness.sh install-desktop | ~/.local/share/applications/agent-control-plane.desktop |
Model calls and pull-request output stay behind the gates in docs/RUNBOOK.md.
Five-minute no-provider demo (evidence check)
No API key, no real provider, no target-repository writes. Builds the engine/dashboard if needed, runs a fixture dispatch, binds proof to the current git revision, and rejects a stale-head scenario:
git clone https://github.com/Igzela/token-efficient-agent-harness-lab.git
cd token-efficient-agent-harness-lab
./scripts/demo.sh
Leave the UI up, or clean a kept session:
./scripts/demo.sh --keep # engine under .acp-demo-state/
./scripts/demo.sh --cleanup # stop and remove .acp-demo-state/
Exact-Head CI proof action (growth wedge)
Use only the fail-closed PR head check without installing the full control plane:
- uses: Igzela/token-efficient-agent-harness-lab/actions/exact-head-check@main
with:
github-token: ${{ github.token }}
pull-request: ${{ github.event.pull_request.number }}
expected-head: ${{ github.event.pull_request.head.sha }}
Details: actions/exact-head-check/README.md · example: examples/github-actions/exact-head-check.yml.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
