feat(queen): runners take tasks and hand the work back for review

[dmitrii-f-t27]

Phase 2 of runner lanes. It is stacked on #518, which registers runners, so review and merge that one first. GitHub will retarget this PR when #518 merges.

A runner created in the app.t27.ai cabinet can now be given a task. It runs the task on its owner's machine with its owner's key and hands back a pushed branch. The existing review judges that branch by the same rules as any container bee's work. The provider key never reaches this server.

How a task flows

1. Offer. dispatchBee asks offerToRunner first, before any key, memory or disk is measured.

   • An idle runner gets a dispatch row on its lane (100000000 + id). The row is started = true and stores the brief, the system prompt and the start commit.
   • Nothing is started locally: no worktree, no /chat, and no provider or model is recorded. Because the row has no provider or model, the daily spend cap never prices the lender's spend.

2. Which issues are offered. Only issues a runner can actually continue:

   • no branch yet;
   • a branch with nothing beyond the base;
   • the runner's own previous push, after a send-back.

   A branch with commits that exist only in the container, or a dirty worktree, stays with the container.

3. Claim. POST /queen/runner/claim hands over the task. Every runner call renews the lease. Claiming again returns the same task, so a runner that restarts picks up where it left off.

4. Complete. POST /queen/runner/complete with {conversationId, remoteUrl, branch, headSha, said}. The server:

   • fetches that one branch into a scratch ref, only from https://github.com/..., with protocol.allow=never and no credential helper;
   • checks the commit is the one named and descends from the offered start;
   • moves queen-<issue> and gives it a clean worktree, as a container bee would leave;
   • writes the agent's answer as the say transcript the review reads;
   • only then closes the row and fires the refill signal.

   A runner can also send {gaveUp: true} to release the issue immediately.

5. Reap. Runner rows are skipped by the boot reaper and the stall reaper. Instead they are released by lease:

   • an offer unclaimed for 10 minutes;
   • a lease not renewed for 15 minutes;
   • any task older than 6 hours.

Effect on the round

• A runner's in-flight row goes on the board as queued. queend already treats that state as a live claim that holds its issue and files, but it does not count it against canStartAnother. So runners add capacity rather than consuming container slots.
• When queend refuses because the container is full, a runner-only pass re-asks it with local bees shown as queued. Each answer goes to an idle runner only. Boundaries, claims and the spend cap still apply.
• Runner lanes are excluded from provider-key accounting:
  • the in-flight takenKeys and keyCursor;
  • runningKeys, used for the reviewer lane;
  • the public research telemetry.
• QUEEN_RUNNERS=off turns offers off, and the swarm runs as it did before. RUNNER_PROTOCOL is now 2.

The runner script

trios/agent-server/tools/queen-runner/queen-runner.mjs plus a README. It needs Node 20+ and git, with no packages to install. It:

• heartbeats and claims;
• checks out the start commit in a worktree on queen-<issue>;
• runs the volunteer's own agent command with the prompt on stdin. The default is claude -p --permission-mode acceptEdits;
• commits whatever the agent left, pushes to the volunteer's public fork, and completes;
• hands the task back on Ctrl-C, on an agent that failed and changed nothing, or when the swarm cannot take the branch.

Tests

What	Result
bun run typecheck	clean
bun run test:api	1359 pass, 59 skip, 0 fail
bun run test:pglive (local PostgreSQL 16)	5 pass, 0 fail
bun run test:root	68 pass, 0 fail
biome check on changed files	no errors; the complexity warnings are the same kind the existing runRound and reviewFinishedDispatches already carry

New tests:

• tests/api/queen-runner-work.test.ts. Uses real git in a temp directory. It covers:
  • which issues a runner may take;
  • the offer row;
  • that an offered task cuts no worktree and measures no container;
  • the runner-only path;
  • body validation: file://, ssh, ext::, other hosts, userinfo, --upload-pack, .. and abbreviated SHAs are all refused;
  • bringing a branch home, wrong SHA, unrelated history, and a checked-out tree;
  • completion ordering, 404 for someone else's task, give-up;
  • the routes.
• tests/api/queen-round-runners.test.ts. Drives runRound against a stand-in policy that applies queend's capacity and claim rules. The real queend is not built in CI, so queen-round.test.ts skips there. Mutation-checked: removing the queued mapping fails one test, and treating runner dispatches as running fails another.
• tests/pglive/queen-runner-work-live.test.ts. The whole life of a task on a migrated scratch database: register, idle, offer, claim, renew, complete, then a review-ready row with the verdict in its transcript. It also covers reaping.
• tests/api/queen-runner-cli.test.ts. Runs the script end to end against a stand-in swarm with local upstream and fork repos, under Bun. It was also run locally under Node 22.

Two existing tests were adjusted:

• queen-runners.test.ts now expects protocol 2.
• The container memory-refusal test in queen-dispatch.test.ts passes offer: null. That test asserts that no queen_dispatch statement is sent, and the runner lookup is a read of that table.

Security notes

• What a runner can trigger in the container. Only a fetch of one branch from github.com over https, pinned and timed out. The criteria runner already executes only an allowlisted read-only command set taken from the issue, as the bee's uid, in a scratch worktree. A runner's commit therefore adds no execution surface that a bee's commit doesn't already have.
• Download size. Any signed-in person can mint a runner, and the container will fetch that runner's branch. The scope is one claimed task per runner, with a 300 s timeout and the existing volume guard. There is no explicit size limit yet. That is a follow-up if abuse appears.
• The project URL. The URL a runner is given has credentials stripped from TRIOS_REPO_URL.

Not done

• Not exercised against the deployed swarm or with a real claude -p run. The CLI test uses a stand-in agent.
• The website copy that points people at the script is gHashTag/trinity, branch claude/runner-claim-complete, stacked on feat(queen): MY RUNNERS cabinet on the leaderboard tab trinity#1205.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SJ8KjRoGNBoHBoDR92fAo2

---

Generated by Claude Code

[github-actions]

✅ Tests passed — 2596/2656

Suite	Passed	Failed	Skipped
✅ agent	87/87	0	0
✅ build	9/9	0	0
✅ cdp-protocol	5/5	0	0
✅ eval	93/93	0	0
✅ server-agent	280/280	0	0
✅ server-api	1443/1502	0	59
✅ server-browser	6/6	0	0
✅ server-integration	10/11	0	1
✅ server-lib	279/279	0	0
✅ server-pglive	27/27	0	0
✅ server-root	68/68	0	0
✅ server-skills	31/31	0	0
✅ server-tools	244/244	0	0
✅ shared	14/14	0	0

View workflow run

[dmitrii-f-t27]

The cla check is red. The CLA Assistant action exits before it reads any signature because the PERSONAL_ACCESS_TOKEN secret is empty (Please add a personal access token as an environment variable...). This PR doesn't cause it, and it fails the same way on #518. No code fix exists: a maintainer needs to set that secret. Every test suite on this head is green (2482 passed, 0 failed, including server-pglive). I can't re-run checks here.

---

Generated by Claude Code

[dmitrii-f-t27]

I've retargeted this PR to fix/queen-worker-provider-and-prompt-size, the production branch, and merged it in (78eb418). This PR still contains #518, so please merge #518 first. Merging this one alone would also bring in #518.

The production branch has gained its own runners (#525). These are the operator's replicas. They claim rows the Queen queued (queued_at / claimed_by) directly from the database and use the operator's keys. The runners in this PR are volunteer machines. They speak only HTTP with a runner token and use their owner's key. The two don't collide:

• Volunteer offers never set queued_at, so operator replicas never claim them.
• Operator rows never sit on a volunteer lane above 100000000.
• dispatchBee asks an idle volunteer runner first. Otherwise it takes the production path: a local bee, or a queued row for an operator replica.

Reapers. The production side had changed the reapers too; I combined both changes. A row is the container's to reap only when neither kind of runner holds it (queued_at IS NULL AND NOT_A_RUNNER). The stall reaper keeps the production branch's silent-runner clause for claimed rows and still skips volunteer lanes; those lanes are released by their own lease reaper.

Local results: test:api 1443 passed, 0 failed; test:pglive 27 passed (including the volunteer-runner live test); test:root 68 passed.

Once this merges, trios/agent-server/tools/queen-runner/queen-runner.mjs exists on the production branch. gHashTag/trinity#1230 will point its download link there.

---

Generated by Claude Code