bon travail

agents find the work. people fix it. proof pays.

live: https://bontravail.xyz (arc testnet). the first real loop is work-001's receipt.

bon travail (the codebase is proofwork) watches the github actions workflow of a repository your team connects. when the same job and step fail twice in a row, it records a finding with github's evidence, and aeon reproduces and bisects it. an engineer then decides: keep the fix in the team, or externalize it to named people with a reward and a deadline. an approved contributor opens a pull request; github actions decides whether it passes; the reward is paid from an escrow contract on arc, or refunded at the deadline. every outcome is sealed in a public receipt, and the observer keeps watching for the failure to come back.

observer   github runs on the default branch -> repeated failure -> finding + evidence
aeon       clone, reproduce red and green, git bisect -> investigation (recommendation only)
engineer   keep internal | dismiss | externalize: reward, deadline, allowlist, acceptance, scope
escrow     usdc moves into proofworkescrow on arc
contributor link a pr that mentions work-00n -> claim -> request verification
github     acceptance job passes on the merge commit (or pr head), protected paths untouched
settle     paid to the allowlisted wallet | refunded at the deadline -> sealed receipt
observer   green resolves the finding; the same failure later is a recurrence

machines discover, prepare and verify. people do the work. engineers own every decision: architecture, secrets, scope, who may claim, the reward and the release. no agent can approve work, choose who is paid, set an amount, or release funds; see docs/security.md.

• docs/architecture.md: modules, data model, state machines, verification
• docs/security.md: authority boundaries and why they exist
• docs/escrow.md: the arc escrow contract and payment lifecycle
• aeon/readme.md: the aeon skills and how to schedule them
• docs/visuals.md: the image set, type and motion system

the site itself has a short guide at /docs.

requires node 22.

npm install
cp .env.example .env.local
# set agent_api_token and session_secret (openssl rand -hex 32 each), owner_github_logins=<your login>
npm run github:app -- --base http://localhost:3000   # once: creates your github app, writes its keys
npm run dev                                         # http://localhost:3000, embedded postgres in ./data/pglite
npm run agent:loop                                  # second terminal: the agent tick every 30s

open /console, sign in with github, then connect github: install the app on the repositories to watch and press watch. the first poll reads the last 30 completed runs of the workflow on the default branch. without an app, github_token=$(gh auth token) and a typed owner/name still work for local development.

npm run demo:seed -- --reset still seeds scripted rail-test history (arc transaction fact-checks) for ui work; it refuses to run against a hosted database.

the public sandbox svector-anu/usdc-sdk-examples has one workflow, examples, with an examples job.

1. break it. push a regression to main twice (two red runs of the same step).
2. observe. the agent tick (or "check now" in the console) turns the repeat into a candidate finding with the log excerpt, the failing command and the commit window.
3. investigate. dispatch the aeon skill: gh workflow run aeon.yml -r <aeon-fork> -f skill=proofwork-investigate -f harness=claude -f var=<base url>. the finding gains aeon's reproduction, first bad commit and proposed acceptance.
4. decide. in the console, open the finding, edit acceptance and scope, set the reward, deadline and allowlist (github login + payout wallet), and approve. the reward is escrowed.
5. fix. as the contributor, open a pr that mentions the work-00n id, paste it on the work page to claim, then "request verification".
6. verify. merge the pr. when the examples job passes on the merge commit, the next tick (or "check again") pays the allowlisted wallet and seals the receipt.
7. watch. the green run resolves the finding. reintroduce the bug and the observer reports a recurrence on the same finding, visible on the receipt's live recurrence panel.

all variables are documented in .env.example. the ones that matter:

1. vercel link, then add neon from the vercel marketplace (it sets database_url). the schema is created on first request.
   create the github app with npm run github:app -- --base https://<your deployment> and copy its five github_app_* values.
2. add the variables above as encrypted environment variables (vercel env add name production). never commit them.
3. vercel deploy --prod. vercel.json registers a daily cron for /api/cron/tick; aeon's proofwork-loop is the real schedule (every 10 minutes).
4. point aeon's proofwork-loop and proofwork-investigate var at the deployment url and set proofwork_agent_token to the deployment's agent_api_token. only point var at a deployment you run. proofwork-investigate clones the repository the deployment names and runs its install and test commands on your aeon runner, so whoever controls that deployment can run code there.

npm run check    # typecheck, lint, tests (pglite, no network), build

contract tests for contracts/proofworkescrow.sol run with foundry: forge test.