in reviewhumanPR #347Transport

Fervo: add agent-contribution adapter and redelivery-idempotency test

Fervo is repo management for agent contributors. It has a server, a runner and a CLI that let many coding agents improve one Git repository safely. An agent claims a scope, commits in its own worktree and submits.

Author

Status
In review
Opened on
Nov 11
Branch
integration/fervo-idempotent-contributions

Description

The pitch.

## Summary

Fervo is repo management for agent contributors. It has a server, a runner and a CLI that let many coding agents improve one Git repository safely. An agent claims a scope, commits in its own worktree and submits. The runner tests and measures the change against its parent, and the server merges it only when the policy is met. Every write carries an idempotency key.

This PR adds `examples/integrations/fervo/`. It contains a Track seller whose unit of work is a real Fervo contribution, a script that cross-checks Town's bundle against Fervo's event log, scripts that set up a reproducible Fervo host, and the recorded evidence. We test this question:

> When Town redelivers work to a Fervo contributor under its fault profiles, does Fervo still record exactly one claim, one node, one merge and one score change?

The PR contains no Fervo source code. Fervo is installed from a pinned commit.

## Integration

| Town | Fervo |
|---|---|
| Buyer sends `quote_request` `q-1` | task: raise `score.txt` in the managed fixture repository |
| Seller claims under a fenced lease | `fervo claim --parent <node> --scope score.txt --checkout --key town-<run>-q-1-claim-0` |
| Seller applies the work | deterministic commit in the lease worktree, then `fervo submit --key town-<run>-q-1-submit-0` |
| Seller responds and acks | waits for `merged`, then replies with the correct total plus a `fervo` block (node, state, merge commit) and acks `processed` |
| Redelivery, fences | Fervo's `(actor, key) → response` idempotency table |

- **`fervo_contributor.py`**: a standard-library participant, like `examples/byoa_seller.py`. It uses the Fervo CLI for keyed writes, which do the Git work, and HTTP for `context` and `status` reads.
  - Keys are derived from the Town run id, the message id and the step. The run id is needed because the buyer reuses `q-1` in every run.
  - The commit is byte-identical on every retry.
  - The chosen parent is recorded in `STATE_DIR` before the claim, so that a replay after the seller's own merge is the same request.
  - The participant acts on `FAULT=crash_after_claim` itself, as Town's scripted seller does: it exits with code 3 after its Fervo claim.
- **`check.py`**: reads the bundle and Fervo's `/events` with the operator token. It asserts 1 claim, 1 node and 1 merge; `score.txt` going 10 → 20; the postmerge check passing; and the node reported to Town being the merged node.
- **Separately hosted service**: the Fervo server (bare repository plus SQLite) runs in a throwaway Lima VM, `fervo-hw8`. It is defined by `lima/fervo-host.yaml`, with a pinned image digest and no host mounts.
  - The Town coordinator, the buyer, the seller, the Fervo runner and the agent clone run on the host. Every push and API call crosses the VM boundary through `127.0.0.1:8775`.
  - `setup_fervo.sh --local` runs the same steps without a VM.

## Reproduce

Requirements: Python 3.11+, Node 24+, Git, and Lima 2.x. A reviewer without Lima can use `--local`.

```sh
# Town, from this branch
python3 -m venv .venv && . .venv/bin/activate
python -m pip install -e '.[dev]'

# Fervo, pinned
git clone https://github.com/PhilStrub/fervo-dev fervo
(cd fervo && git checkout v0.1.0-hw8 && npm ci && npm run build &&
 tar czf ../fervo.tgz package.json package-lock.json dist/src skill)

# The matrix: each row resets Fervo, runs Town, cross-checks, verifies, and writes evidence/<row>/
export FERVO_TGZ=$PWD/fervo.tgz FERVO_REF=cafaa82
examples/integrations/fervo/run_matrix.sh --lima      # or --local; host port 8775 must be free
examples/integrations/fervo/teardown_fervo.sh
```

Each row runs:

```sh
nandatown test-agent --role seller --profile <profile> \
  --cmd "python3 examples/integrations/fervo/fervo_contributor.py"
python3 examples/integrations/fervo/check.py <bundle>
nandatown verify <bundle> && nandatown receipt <bundle>
```

The offline check needs no Fervo. It verifies the committed bundles

…

Try it

Open PR on GitHubView diff

Checkout locally

git fetch origin pull/347/head:pr-347
git checkout pr-347