The idea: work that bids for itself
Code Fleet is the coding-swarm scenario in one 443-line class. A repository's issues become Issue entries in a replicated space. Three coding agents, each on a peer of its own, price every issue with a cost model and claim the one they can do most cheaply. The space keeps the lowest bid, the winning coder does the work, and two review agents take the finished changes and report CI. The app contains no dispatcher, no queue broker and no scheduler: the allocation falls out of three bid functions and the claim rule the space applies to them.
The economics make the result easy to read. The two specialists price their own area at 3 per unit of difficulty and everything else at 9. The sweeper has no specialty and bids 6 per unit on every issue, so it takes the mechanical infra work while the specialists take their own areas. The demo then kills the sweeper on its third take. Its lease lapses after 5 seconds, the issue comes back, and the two specialists, the only bidders left, take it at 36, three times their own rate.
Three things make the example worth reading. Capacity routes itself to the work it fits, which is the point of the AUCTION strategy. The work survives its workers, because a take is a lease and a lapsed lease sends the entry back. And the whole allocation stays legible afterwards: every winner writes its result into the issues space under its own key, so the space is the ledger of who did what at what price.
The cast: three coders, two reviewers, one coordinator
The group has six peers and five agents. Each agent is a plain Java object annotated for the binder: the Coder and the Reviewer are the only two agent classes. The coordinator is a peer with no agent on it. The demo's main and the test play that role by writing issues and reading CI results directly on its replicas.
| Agent | Class and annotations | Peers in the demo | Reads and writes |
|---|---|---|---|
| coordinator (no agent) | the demo's main and the test call issues().write(...) and changes().readAll(...) | coordinator :7571, the seed | writes Issue to issues (10 min lease, peer-signed); reads CiResult and the CodeChange copies in changes, and the CodeChange results in issues |
| coder (three) | CodeFleet.Coder; @AgentSpec(name = "coder", goals = {"code"}), @BidFunction(space = issues), @SpaceTake(space = issues, lease = "5s"), @SpaceRef(changes) | coder-frontend :7572coder-backend :7573coder-sweeper :7574 | takes Issue from issues; writes CodeChange to issues as the completion result, and a copy to changes |
| reviewer (two) | CodeFleet.Reviewer; @AgentSpec(name = "reviewer", goals = {"review"}), @SpaceTake(space = changes, lease = "5s"), @SpaceRef(changes) | review-a :7575review-b :7576 | takes CodeChange from changes; writes Review as the completion result, and a CiResult on approval |
The three coders differ only in the numbers handed to costModel. The frontend and backend coders carry an expertise string and a price of 3 per unit. The sweeper carries the expertise "any", a price of 2 per unit, and a limit of 2 completed changes, after which its next take fails on purpose (chapter 10). Both reviewers carry a skill of 10, which sets the largest cost they approve. Every take annotation also names a poll timeout of 2 s and a result lease of 1 h: a take loop polls for 2 s and polls again, and a completion's result entry lives for 1 h.
/** * Binds a coder on its peer. * * @param peer the coder's peer * @param costModel its bid * @param dieAfter changes to complete before dying mid-take, or -1 to live * @return the bound coder; close it to stop it, or ask it whether it died */ public static Coder runCoder(Peer peer, ToDoubleFunction<Object> costModel, int dieAfter) { Coder coder = new Coder(peer.name(), costModel, dieAfter); coder.binding = peer.group().bind(coder); return coder; }
/** * Binds a reviewer on its peer. * * @param peer the reviewer's peer * @param skill the largest change cost it will approve, in tens * @return the binding; close it to stop the reviewer */ public static AutoCloseable runReviewer(Peer peer, int skill) { return peer.group().bind(new Reviewer(peer.name(), skill)); }
agents.add(runCoder(frontend, costModel("frontend", 3.0), -1)); agents.add(runCoder(backend, costModel("backend", 3.0), -1)); Coder sweeperCoder = runCoder(sweeper, costModel("any", 2.0), 2); agents.add(sweeperCoder); agents.add(runReviewer(reviewerA, 10)); agents.add(runReviewer(reviewerB, 10));
@BidFunction on the same space of one peer, by name, so each coder sits on its own peer. The reviewers bind no bid function at all, because only an AUCTION space consults one and they take from a LEASE_RACE space.How the fleet forms and how work finds a coder
Every peer builds the same group advertisement from the same literal founding, listens on a TCP port, and dials one seed. The first peer to start, the coordinator, is the seed and dials nobody. The other five dial it, learn the other members through it, and open their replicas of the two spaces before the first tick.
| Setting | Value in the app | Where it comes from |
|---|---|---|
| group name | code-fleet | GroupAdvertisement in CodeFleet.group() |
| founding | the literal text code-fleet-v1; the group id is the base58 SHA-256 of those bytes | GroupId.fromFounding(...) |
| membership policy | OPEN, anyone who reaches a seed joins | the same advertisement |
| advertised default strategy | AUCTION; each space still declares its own (chapter 4) | the same advertisement |
| seed | the coordinator at 127.0.0.1:7571 in the demo; the test takes a free port per peer and passes the first as the seed | startPeer(name, port, seedPort) |
| transport | TCP only, one TcpTransport per peer, listening on 127.0.0.1 | node.listen(...) |
| security | a fresh Ed25519 identity per peer, every frame signed (the node's default channel authentication), plain TCP without TLS | PeerIdentity.generate(), PeerNode.builder(identity).build() |
| membership tuning | member ttl 30 s, ping timeout 2 s, 2 indirect probes, one probe per second | GroupMembership.Config |
| gossip | fanout 3, period 1 s, the advertisement's defaults | GossipParameters.defaults() |
| tick | 250 ms | node.startTicking(...) |
A literal founding is the simple way to fix a group in code, and it has one consequence worth knowing: nothing can ask for the group by its id, because no signed founding document exists to serve. Every peer dials the seed, which is why startPeer takes the seed port. A fleet that wants join-by-id signs a founding document instead, as the developer guide's section on finding the group describes.
/** * Assembles one peer. The issue space runs AUCTION and the change space runs * LEASE_RACE. The peer carries no bid function until a coder binds: the coder's * {@code @BidFunction} installs its cost model on the issue space. * * @param name the peer's name, also the writer name of its replicas * @param port the TCP port * @param seedPort an existing member's port, or 0 for the first * @return the running peer * @throws Exception if the port cannot be bound */ public static Peer startPeer(String name, int port, int seedPort) throws Exception { PeerIdentity identity = PeerIdentity.generate(); PeerNode node = PeerNode.builder(identity).build(); node.listen(new TcpTransport(), HOST + ":" + port); List<PeerAdvertisement.Endpoint> seeds = seedPort == 0 ? List.of() : List.of(new PeerAdvertisement.Endpoint("tcp", HOST + ":" + seedPort, 0)); GroupRuntime runtime = node.joinGroup(group(), new GroupMembership.Config(Duration.ofSeconds(30), Duration.ofSeconds(2), 2), seeds); // No bid on the builder: a coder's @BidFunction prices the AUCTION space at // bind time, and a coordinator or reviewer, which never takes an issue, // carries none. A space accepts one bid function per peer, so a placeholder // on a non-bidder would block the coder that needs the slot. ReplicatedSpace issues = ReplicatedSpace.builder(runtime, ISSUES, identity, name) .settleWindow(Duration.ofMillis(250)) .strategy(ConflictStrategyType.AUCTION) .build(); ReplicatedSpace changes = ReplicatedSpace.builder(runtime, CHANGES, identity, name) .settleWindow(Duration.ofMillis(150)) .build(); // The agents are annotated POJOs bound through the facade. With the renewing // subordinate identity factory (a certificate that renews at half of 24 h), // each one signs its changes with a certified key of its own, and its // @SpaceRef is a per-agent view of the replica, so "who won each issue" is // the authenticated, attested issuer of the change. AgentSpaces spaces = new AgentSpaces(identity, InstantSource.system(), agentName -> identity.renewingSubordinate(agentName, java.time.Duration.ofHours(24), java.time.InstantSource.system())); AgentSpaces.GroupContext group = spaces.register("code-fleet", runtime.id(), runtime, null); group.space(ISSUES, issues); group.space(CHANGES, changes); node.startTicking(Duration.ofMillis(250)); return new Peer(name, node, runtime, issues, changes, group); }
/** * The code-fleet group. Its advertisement names AUCTION as the group's default * strategy, and each space still declares its own: {@link #startPeer} builds the * issues space with AUCTION and the changes space with the builder default, * LEASE_RACE. The founding is a literal text, so peers join by dialing a seed. */ public static GroupAdvertisement group() { GroupId groupId = GroupId.fromFounding( "code-fleet-v1".getBytes(StandardCharsets.UTF_8)); return new GroupAdvertisement("aspace://" + groupId.value(), PeerIdentity.generate().peerId(), groupId, Instant.EPOCH, Duration.ofDays(365), "code-fleet", GroupAdvertisement.MembershipPolicy.OPEN, ConflictStrategyType.AUCTION, GroupAdvertisement.GossipParameters.defaults()); }
Finding work without cards
Code Fleet uses discovery only for membership. spaces.register("code-fleet", runtime.id(), runtime, null) hands the facade no DiscoveryService, so the binder builds each agent's card and keeps it in Bound.card() without publishing it. The spaces advertise nothing either, because neither builder calls advertise(...). A coder finds an issue by type: the binder turns the parameter of code(Issue) into a template on the issues space, and the take loop polls it.
The routing rule that follows is the one the developer guide recommends: send work by entry type through a space, and treat a card as a hint for a reader such as a console or a planner. Passing a DiscoveryService as the fourth argument would publish five cards, each carrying the agent's goal, what it consumes and produces, and its own key and certificate.
The spaces: an auction ledger and a review race
Two replicated spaces carry the work, each with a strategy that matches the job. The issues space runs AUCTION with a 250 ms settle window. The changes space takes the builder default, LEASE_RACE, with a 150 ms window. Each peer builds both and holds a full replica of each.
| Space | Strategy | Records | Leases | Who writes |
|---|---|---|---|---|
| issues | AUCTION, settle 250 ms | Issue in, CodeChange out as the completion result | issue 10 min, take 5 s, result 1 h | the coordinator writes the issue; the winning coder writes the result under its own key |
| changes | LEASE_RACE, settle 150 ms | CodeChange copy in, Review out as the completion result, CiResult beside it | copy 1 h, take 5 s, review 1 h, CI 1 h | the coder writes the copy, the reviewer writes the review and the CI result |
ReplicatedSpace issues = ReplicatedSpace.builder(runtime, ISSUES, identity, name) .settleWindow(Duration.ofMillis(250)) .strategy(ConflictStrategyType.AUCTION) .build(); ReplicatedSpace changes = ReplicatedSpace.builder(runtime, CHANGES, identity, name) .settleWindow(Duration.ofMillis(150)) .build();
/** A repository task: an issue or a migration step, in some area. */ public record Issue(String issueId, String area, int difficulty) { } /** A change a coding agent produced for an issue, priced at its winning bid. */ public record CodeChange(String issueId, String area, String byAgent, double cost) { } /** A review agent's verdict on a change. */ public record Review(String issueId, String byReviewer, boolean approved, String note) { } /** A CI result for an approved change. */ public record CiResult(String issueId, boolean passed) { }
The records are small on purpose. A CodeChange names the issue, the area, the agent that produced it, and its cost, which is the winning bid. Because the winner's result lands in the issues space beside the work it finished, a reader of that one space sees every allocation and its price.
One run, end to end
The flow below is one issue travelling through the fleet. The coordinator writes it, the coders bid, one coder codes it, a reviewer takes the copy, and the coordinator reads the CI result. The code under each step is the whole of it: there is no hidden orchestrator.
Steps 1 to 3: write, price, settle
The coordinator writes 9 issues in a loop. The area comes from i % 3 and the difficulty from 1 + (i % 5), so the demo has three frontend issues, three backend issues and three infra issues with difficulties 1 to 5. Each write is an entry with a 10 minute lease. A coder's take loop sees it as soon as gossip delivers it, prices it, and claims the issue it can do most cheaply (chapter 7).
String[] areas = {"frontend", "backend", "infra"}; int issueCount = 9; for (int i = 1; i <= issueCount; i++) { coordinator.issues().write(new Issue("ISSUE-" + i, areas[i % 3], 1 + (i % 5)), Lease.of(Duration.ofMinutes(10))); }
Steps 4 to 6: code, copy, complete
The winner's code method runs once the settle window has confirmed its claim. It sleeps 300 ms for the coding work, renews its take lease, writes a copy of its change to the review space, and returns the change. The renew is a check as well as an extension: it throws when a lower bid has displaced the claim, and the coder then writes nothing (chapter 7). The binder completes the take with the returned value as the result entry, which is how the issues space becomes the ledger. The copy goes before the completion because the binder completes the take only when the method returns, so a reviewer can already hold the change by the time the issue completes.
@SpaceTake(space = ISSUES, lease = "5s", pollTimeout = "2s", resultLease = "1h") public CodeChange code(Issue issue) { if (dieAfter >= 0 && done >= dieAfter) { // Crash mid-take: stop this agent and abandon the held issue. The // binder never completes a take whose action threw, so the 5 s lease // lapses and the issue reappears for another coder. abandoned = issue; close(); throw new IllegalStateException(label + " died mid-take"); } double cost = costModel.applyAsDouble(issue); sleep(300); // the coding work // Still the holder? A lower bid can reach this replica after our settle // window and displace the claim. renew throws LeaseExpiredException then, // so a displaced coder writes no review copy and no result, and the // binder logs the failed action and returns the coder to its take loop. TakeContext.current().ifPresent(TakeContext::renew); CodeChange change = new CodeChange(issue.issueId(), issue.area(), label, cost); changes.write(change, Lease.of(Duration.ofHours(1))); // for review done++; return change; // completes the take with the change as its result }
/** * A coder: bids for issues by its cost model and takes the ones it wins. * The take is a leased, exclusive {@code @SpaceTake}; the returned * {@link CodeChange} is written as the completion's result, and a copy goes * to the review space for the reviewers to take. Before it writes that copy, * the coder renews its take lease, which throws when a lower bid displaced * its claim, so a displaced coder writes no copy and no result. A coder told * to die after {@code dieAfter} changes crashes mid-take: it closes its own * binding and throws, so the take lease lapses and the issue reappears for * someone else. Closing the coder closes its binding. */ @AgentSpec(name = "coder", description = "Bids on issues by expertise and codes the ones it wins", goals = {"code"}) public static final class Coder implements AutoCloseable { private final String label; private final ToDoubleFunction<Object> costModel; private final int dieAfter; private int done; private volatile Issue abandoned; volatile AgentBinder.Bound binding; @SpaceRef(CHANGES) Space changes; public Coder(String label, ToDoubleFunction<Object> costModel, int dieAfter) { this.label = label; this.costModel = costModel; this.dieAfter = dieAfter; } @BidFunction(space = ISSUES) public double bid(Issue issue) { return costModel.applyAsDouble(issue); } @SpaceTake(space = ISSUES, lease = "5s", pollTimeout = "2s", resultLease = "1h") public CodeChange code(Issue issue) { if (dieAfter >= 0 && done >= dieAfter) { // Crash mid-take: stop this agent and abandon the held issue. The // binder never completes a take whose action threw, so the 5 s lease // lapses and the issue reappears for another coder. abandoned = issue; close(); throw new IllegalStateException(label + " died mid-take"); } double cost = costModel.applyAsDouble(issue); sleep(300); // the coding work // Still the holder? A lower bid can reach this replica after our settle // window and displace the claim. renew throws LeaseExpiredException then, // so a displaced coder writes no review copy and no result, and the // binder logs the failed action and returns the coder to its take loop. TakeContext.current().ifPresent(TakeContext::renew); CodeChange change = new CodeChange(issue.issueId(), issue.area(), label, cost); changes.write(change, Lease.of(Duration.ofHours(1))); // for review done++; return change; // completes the take with the change as its result } /** * Returns the issue this coder died holding, or {@code null} while it lives * or when it never reached its fatal take. * * @return the abandoned issue, or null */ public Issue abandoned() { return abandoned; } /** * Returns whether this coder crashed mid-take on its {@code dieAfter}. * * @return true once it abandoned an issue */ public boolean died() { return abandoned != null; } /** Stops the coder by closing its binding. */ @Override public void close() { AgentBinder.Bound mine = binding; if (mine != null) { mine.close(); } } }
Steps 7 to 9: review and CI
A reviewer takes the copy from the changes space under LEASE_RACE, spends 150 ms reviewing, approves it when its cost is at most 100, and then writes a passing CiResult and returns the Review. The coordinator polls the changes space for CiResult entries and stops when 9 different issues have a passing one. Chapter 8 follows that loop in detail.
for (int tick = 0; tick < 30; tick++) { // Count issues, not entries: a duplicate CiResult must not end the wait early. long ciPassed = coordinator.changes().readAll(Template.of(CiResult.class), 100) .stream().filter(CiResult::passed).map(CiResult::issueId) .distinct().count(); long allocated = coordinator.issues() .readAll(Template.of(CodeChange.class), 100).stream() .map(CodeChange::issueId).distinct().count(); System.out.printf(" allocated=%d in-review=%d ci-passed=%d%n", allocated, coordinator.changes().readAll(Template.of(CodeChange.class), 100).size(), ciPassed); if (ciPassed >= issueCount) { break; } sleep(1000); }
A recorded run
This is the demo's output from 2026-11-04, verbatim. The three progress columns come from the coordinator's replicas: allocated counts the distinct issues that have a completion in the issues space, in-review counts copies in the changes space that no reviewer holds yet, and ci-passed counts the distinct issues that have a passing CiResult. in-review stays at 0 because a free reviewer claims a copy within a poll or two and a held entry drops out of readAll.
code-fleet: cost-aware coding swarm, no dispatcher 9 issues published across frontend/backend/infra; agents bid by expertise and cost: allocated=0 in-review=0 ci-passed=0 allocated=3 in-review=0 ci-passed=1 allocated=8 in-review=0 ci-passed=7 allocated=8 in-review=0 ci-passed=8 allocated=8 in-review=0 ci-passed=8 allocated=8 in-review=0 ci-passed=8 allocated=8 in-review=0 ci-passed=8 allocated=9 in-review=0 ci-passed=8 allocated=9 in-review=0 ci-passed=9 == allocation (who won each issue, and at what cost) == ISSUE-1 backend -> coder-backend cost 6 (peer:zHB64ubkqo…, AGENT_ATTESTED) ISSUE-2 infra -> coder-sweeper cost 18 (peer:zDjVktTQbx…, AGENT_ATTESTED) ISSUE-3 frontend -> coder-frontend cost 12 (peer:z79kNcttZf…, AGENT_ATTESTED) ISSUE-4 backend -> coder-backend cost 15 (peer:zHB64ubkqo…, AGENT_ATTESTED) ISSUE-5 infra -> coder-sweeper cost 6 (peer:zDjVktTQbx…, AGENT_ATTESTED) ISSUE-6 frontend -> coder-frontend cost 6 (peer:z79kNcttZf…, AGENT_ATTESTED) ISSUE-7 backend -> coder-backend cost 9 (peer:zHB64ubkqo…, AGENT_ATTESTED) ISSUE-8 infra -> coder-frontend cost 36 (peer:z79kNcttZf…, AGENT_ATTESTED) ISSUE-9 frontend -> coder-frontend cost 15 (peer:z79kNcttZf…, AGENT_ATTESTED) changes per agent: {coder-backend=3, coder-frontend=4, coder-sweeper=2} The sweeper died on ISSUE-8 (its bid was 24) after 2 changes. Its lease lapsed and coder-frontend finished ISSUE-8 at cost 36. 9 of 9 issues allocated, with no central dispatcher.
The allocation table is the ledger. Each row is the issuer-attributed result the winning coder wrote, with the issuer's peer and its attestation printed beside the byAgent label the change declares. A displaced coder writes no result, so each issue shows one row. The view still keeps the cheaper change per issue, in case a duplicate lands in the few milliseconds between a winner's renew and its completion (chapter 7). The last lines report what happened to the sweeper. The demo asks the sweeper's Coder whether it died and on which issue, prices that issue with the sweeper's own cost model, and names the coder that finished it. When the sweeper never reaches a third take, the text says that nobody died.
Map<String, ai.badmonkey.agentspaces.api.space.Space.Issued<CodeChange>> winners = new java.util.TreeMap<>(); coordinator.issues().readAllIssued(Template.of(CodeChange.class), 100).forEach(c -> winners.merge(c.entry().issueId(), c, (a, b) -> a.entry().cost() <= b.entry().cost() ? a : b)); // Every coder is bound as "coder", so the issuer names the peer; the // change's byAgent label is the readable name. CodeFleetTest checks // that the two agree. winners.values().forEach(c -> System.out.printf( " %-9s %-9s -> %-16s cost %.0f (%s, %s)%n", c.entry().issueId(), c.entry().area(), c.entry().byAgent(), c.entry().cost(), c.issuer().peer().display(), c.attestation())); Map<String, Long> perAgent = new java.util.TreeMap<>(); winners.values().forEach(c -> perAgent.merge(c.entry().byAgent(), 1L, Long::sum));
Issue orphan = sweeperCoder.abandoned(); if (orphan == null) { System.out.println("\nThe sweeper never reached its third take, so nobody died in this run."); } else { double sweeperBid = costModel("any", 2.0).applyAsDouble(orphan); System.out.printf("%nThe sweeper died on %s (its bid was %.0f) after %d changes.%n", orphan.issueId(), sweeperBid, perAgent.getOrDefault("coder-sweeper", 0L)); var rerun = winners.get(orphan.issueId()); if (rerun == null) { System.out.println(orphan.issueId() + " had not been picked up again when the demo stopped waiting."); } else { System.out.printf("Its lease lapsed and %s finished %s at cost %.0f.%n", rerun.entry().byAgent(), orphan.issueId(), rerun.entry().cost()); } } System.out.printf("%d of %d issues allocated, with no central dispatcher.%n", winners.size(), issueCount);
The price of work: the bid functions
The whole policy of the fleet is one small method. costModel(expertise, costPerUnit) returns a function from an issue to a price: the price per unit times the issue's difficulty, multiplied by 3 when the issue's area is not the coder's expertise. The coder's @BidFunction calls it, and the binder hands the method to the issues replica as its cost function when the coder binds.
/** * A coder's cost model: {@code costPerUnit} times the issue's difficulty, tripled * when the issue's area is not {@code expertise}. The comparison is * {@code equals}, so an expertise that names no area, such as {@code "any"}, * never matches and the price is tripled on every issue. * * @param expertise the area this coder prices at its own rate * @param costPerUnit its price per unit of difficulty * @return the bid function over {@link Issue}s */ public static ToDoubleFunction<Object> costModel(String expertise, double costPerUnit) { return entry -> { Issue issue = (Issue) entry; double base = costPerUnit * issue.difficulty(); return issue.area().equals(expertise) ? base : base * 3.0; }; }
@BidFunction(space = ISSUES) public double bid(Issue issue) { return costModel.applyAsDouble(issue); }
Read the matrix by rows. On ISSUE-1, a backend issue of difficulty 2, the backend coder bids 6, the sweeper 12 and the frontend coder 18. On ISSUE-2, an infra issue of difficulty 3, nobody has the expertise, so the sweeper's 18 undercuts the specialists' 27. On ISSUE-8, an infra issue of difficulty 4, the sweeper bids 24 and the specialists 36, which is the row the kill story in chapter 10 turns on.
The sweeper's price deserves a close look. Its expertise is the string "any", and costModel compares it to the issue's area with equals, so it never matches and the sweeper pays the factor of 3 on every issue. The result is a ladder of three rungs, shown below. A reading of "any" as a wildcard would price the sweeper at 2 per unit, under both specialists on their own areas, and it would take every issue. The ladder is what makes the demo's division of labor work, and it comes from that one comparison.
What to watch for in a bid function
- Use one unit. The space compares bids directly, so every coder prices in the same unit. Here it is an abstract cost; a real fleet might denominate dollars or tokens.
- Keep it fast and pure. The space calls the function for every live issue of the type on every poll, about every 20 ms per idle coder. This one is plain arithmetic, while a bid that called a model or a database would slow every claim.
- Price the same way twice. The claim carries the bid computed at claim time, and
code()computes the cost again for the change. The two agree because the model is deterministic, and the recorded costs equal the winning bids. - Check the strategy first. A
@BidFunctionon a LEASE_RACE space is never called. When an auction behaves like a race, look at the space's strategy before the function.
One auction round
An auction here has no auctioneer and no bidding phase. Each coder with a free take loop looks at the issues its replica holds, runs its bid function over them, sorts by its own price, and claims the cheapest one it can. A claim is a signed record: the entry it is for, an epoch, the holder, the bid, an HLC stamp and an expiry. Claims travel by gossip like any other state, and every replica merges them with the same rule, so replicas that have seen the same claims agree on the holder with no coordination.
Replicas apply one merge rule to the claims they hold, and that rule decides the auction. A higher epoch supersedes. Within an epoch the lowest bid holds. Equal bids go to the lower stamp, then to the lower holder id. After it claims, a coder sleeps for the settle window, 250 ms here, and then checks whether its claim is still the one in force. If it is, the take succeeds. If another replica's lower bid reached it during the window, the take fails quietly and the coder moves on to its next candidate. A challenger has a limit of its own: a coder may counter-claim an issue another coder holds only with a strictly lower bid, and only while the holder's settle window is open.
The picture comes from a traced run. Two coders claimed ISSUE-7 within a few milliseconds of each other, the sweeper at 18 and the backend coder at 9. The lattice kept 9, the sweeper's window closed with its claim lost, and it moved on to ISSUE-2 about 259 ms after its first claim. The listing below is the observer's output for that issue, verbatim. The observer is a scratch program that lives outside the app: it subscribed Space.notify on the coordinator's replicas and logged the first price each cost model computed per issue.
38 ms issues WRITTEN ISSUE-7 by coordinator/coordinator 44 ms bid backend prices ISSUE-7 (backend, d3) at 9.0 617 ms bid sweeper prices ISSUE-7 (backend, d3) at 18.0 621 ms bid frontend prices ISSUE-7 (backend, d3) at 27.0 642 ms issues TAKEN ISSUE-7 by coder-sweeper/coder 901 ms issues TAKEN ISSUE-2 by coder-sweeper/coder 1183 ms changes WRITTEN CodeChange ISSUE-7 by coder-backend/coder 1189 ms issues COMPLETED ISSUE-7 by coder-backend/coder 1193 ms issues WRITTEN CodeChange ISSUE-7 cost 9.0 byAgent coder-backend 1206 ms changes TAKEN CodeChange ISSUE-7 by review-a/reviewer 1519 ms changes WRITTEN CiResult ISSUE-7 passed=true 1525 ms changes COMPLETED CodeChange ISSUE-7 by review-a/reviewer 1530 ms changes WRITTEN Review ISSUE-7 review-a LGTM
One detail in that listing is easy to misread. TAKEN ISSUE-7 by coder-sweeper is the first claim the coordinator's replica merged. A replica fires TAKEN once per claim epoch, so a watcher that is not the claimant hears the first claim it merges and not the final holder. The COMPLETED event names the holder that finished, which was the backend coder. A reader who needs the final holder should wait for the completion or read the result entry.
What the rounds teach
- An issue waits for a free coder. The coordinator wrote ISSUE-7 at 38 ms, and its first claim reached the coordinator at 642 ms, after the three coders finished their first changes. Each coder runs one take at a time, so 9 issues on three coders run in about three waves.
- The window limits when a counter-claim can be made, and every replica merges it whenever it arrives. A claim travels by gossip like any other state, so a lower bid made inside the window can reach a holder after the window has closed. The merge rule still gives the issue to the lower bid, and the holder, which believed it had won, finds out when it next asks its replica. In the trace the claims of the first wave reached the coordinator within about ten milliseconds, far inside the window. On a slow or loaded link the delay can be longer.
- A holder can learn late that it lost. A checking run on 2026-11-04, made before the coder guarded its copy, showed it. One coder's completion failed with
LeaseExpiredException: take lease lapsed or lostabout half a second after its claim, far inside its 5 s lease, so another claim had displaced it after its own settle window passed. Its copy was already in the changes space, because the copy goes first, and the reviewers saw a second change for that issue. The coder now checks before it writes the copy, as the next section shows. - A claim carries a lease. The holder has 5 s from the claim. Chapters 8 and 10 use that: a reviewer's take would lapse the same way, and a coder that dies leaves its claim to run out.
A displaced coder checks before it writes
The coder's code method asks its replica once more after the work and before the copy. TakeContext.current() returns the take the binder is running, and renew() extends its lease by the binding's lease, 5 s here. The replica also checks the claim when it renews: it throws LeaseExpiredException when the claim in force names another holder or epoch, or has expired. A displaced coder therefore stops at the renew. It writes no review copy and returns no result, so the binder has no completion to attempt. It logs the failed action at WARNING and the coder polls for its next issue. The reviewers see one copy per issue, the winner's, and write one CiResult.
// Still the holder? A lower bid can reach this replica after our settle // window and displace the claim. renew throws LeaseExpiredException then, // so a displaced coder writes no review copy and no result, and the // binder logs the failed action and returns the coder to its take loop. TakeContext.current().ifPresent(TakeContext::renew); CodeChange change = new CodeChange(issue.issueId(), issue.area(), label, cost); changes.write(change, Lease.of(Duration.ofHours(1))); // for review done++;
A displacement after the holder's own window is rare under the app's windows, 250 ms on every peer, so a scratch program outside the app forces it. It runs two coders on two peers. Coder-a sits on a peer whose issues window is 5 ms and prices the issue at 18. Coder-b sits on a peer whose window is 3000 ms and prices it at 3, and the program binds it 120 ms after it writes the issue. Coder-a claims the issue and starts its 300 ms of work. Coder-b then counter-claims with the lower bid, which its long window allows, and the claim reaches coder-a's replica during the work. The listing is that program's output on 2026-11-04, followed by the first lines of the WARNING the binder logged for coder-a. Both coders bind under the local name coder, which is why the events read by coder. Only coder-b writes a copy, and the throw in the stack comes from renew, called by Coder.code. Against the earlier Coder, which had no renew, the same program showed coder-a's copy written at 372 ms and a completion that failed in completeInternal.
14 ms issues WRITTEN ISSUE-X by coordinator 35 ms issues TAKEN ISSUE-X by coder 141 ms binding coder-b (price 3) while coder-a (price 18) works 3468 ms changes WRITTEN CodeChange ISSUE-X byAgent coder-b 3474 ms issues COMPLETED ISSUE-X by coder 3478 ms issues WRITTEN CodeChange ISSUE-X byAgent coder-b WARNING: coder.code: action failed; lease will lapse ai.badmonkey.agentspaces.api.error.LeaseExpiredException: take lease lapsed for entry e1208299-0afa-4c61-8055-27d8b0a916ed at ai.badmonkey.agentspaces.space.replicated.ReplicatedSpace$Taken.renew(ReplicatedSpace.java:3246) at ai.badmonkey.agentspaces.agent.TakeContext.renew(TakeContext.java:88) at ai.badmonkey.agentspaces.flagship.code.CodeFleet$Coder.code(CodeFleet.java:236)
The check narrows the window and leaves a few milliseconds open. The binder completes the take only when code returns, so the app cannot write the copy after the completion, and a lower bid merged between the renew and the completion would still leave a duplicate copy. Two places absorb that case. The demo's progress loop counts distinct issue ids with a passing CiResult, so a duplicate cannot end the wait early, and the flow test checks distinct ids in both spaces, so a duplicate cannot stand in for a missing issue.
Review and CI close the loop
The changes space runs LEASE_RACE with a 150 ms window, which suits a job any reviewer can do. A reviewer carries no bid function. It takes a CodeChange, spends 150 ms on the review, and approves when change.cost() <= skill * 10. With a skill of 10 the threshold is 100, and no price in the demo exceeds 45, so the reviewers approve every change.
@SpaceTake(space = CHANGES, lease = "5s", pollTimeout = "2s", resultLease = "1h") public Review review(CodeChange change) { sleep(150); // the review work boolean approved = change.cost() <= skill * 10.0; if (approved) { changes.write(new CiResult(change.issueId(), true), Lease.of(Duration.ofHours(1))); } return new Review(change.issueId(), label, approved, approved ? "LGTM" : "needs work"); }
/** * A reviewer: takes changes from the review space, approves those within its * skill, writes the {@link Review} as the completion's result and, for an * approval, a passing {@link CiResult}. */ @AgentSpec(name = "reviewer", description = "Reviews changes and reports CI", goals = {"review"}) public static final class Reviewer { private final String label; private final int skill; @SpaceRef(CHANGES) Space changes; public Reviewer(String label, int skill) { this.label = label; this.skill = skill; } @SpaceTake(space = CHANGES, lease = "5s", pollTimeout = "2s", resultLease = "1h") public Review review(CodeChange change) { sleep(150); // the review work boolean approved = change.cost() <= skill * 10.0; if (approved) { changes.write(new CiResult(change.issueId(), true), Lease.of(Duration.ofHours(1))); } return new Review(change.issueId(), label, approved, approved ? "LGTM" : "needs work"); } }
The loop closes in the coordinator. It polls the changes space for CiResult entries and counts the distinct issues among them until it reaches 9. The reviewer writes that CiResult itself, so it stands in for a CI runner: in a real fleet a build agent would take approved changes and write the result. The take uses the same shape. A reviewer that died mid-review would let its 5 s lease lapse, and the copy would reappear for the other reviewer.
CiResult. An earlier version of the loop counted entries. In a checking run on 2026-11-04 a displaced coder's copy had been reviewed too, so the entry count reached 9 while the issues space held 8 results and the sweeper's issue had not been re-run yet, and the loop would have stopped early. The coder's renew check now keeps that copy from existing, and counting ids covers a duplicate that slips through the gap before the completion. A fleet that stops on a count should count the set of ids.Review with approved = false and no CiResult. Nothing consumes that review, so nothing reopens the issue and the coordinator would wait for a CI result that never arrives. The README names the missing piece, a rejection path that reopens the issue for a propose, review and revise loop. The Review.approved flag is already there for it.Every agent signs as itself
The app builds the facade with an identity factory, and that one argument changes what the rest of the fleet can prove. Without it, every agent on a peer signs with the peer's key and a reader can name only the peer. With identity.renewingSubordinate(agentName, 24 h, clock), each bound agent gets an Ed25519 key of its own, certified by its peer, and the binder hands it a per-agent view of each replica.
// The agents are annotated POJOs bound through the facade. With the renewing // subordinate identity factory (a certificate that renews at half of 24 h), // each one signs its changes with a certified key of its own, and its // @SpaceRef is a per-agent view of the replica, so "who won each issue" is // the authenticated, attested issuer of the change. AgentSpaces spaces = new AgentSpaces(identity, InstantSource.system(), agentName -> identity.renewingSubordinate(agentName, java.time.Duration.ofHours(24), java.time.InstantSource.system())); AgentSpaces.GroupContext group = spaces.register("code-fleet", runtime.id(), runtime, null); group.space(ISSUES, issues); group.space(CHANGES, changes);
A view is the same replica under another identity: one gossip registration and one clock per node, with the writer swapped. The agent issues and signs every write through it, and a claim or completion through it names the agent as the holder. The coder's take loop takes and completes through that view, and its @SpaceRef field holds a view of the changes space, so even the copy it writes for review carries its key.
The reader's side is readAllIssued, which returns each entry with its issuer and an attestation: AGENT_ATTESTED when the entry carries an agent certificate, PEER_ASSERTED when only the peer vouches for it. The coordinator writes issues under its peer's key and binds no agent, so its entries read as asserted. The coders' results read as attested.
The byAgent field is a different matter: it is a label the writer chose. The test checks the label against the evidence, and the demo prints both so a reader can compare them.
// Attribution is evidence: every change's declared author is // its authenticated issuer, and every change is signed by that agent's own // certified key. java.util.Map<String, ai.badmonkey.agentspaces.common.id.PeerId> peerOf = new java.util.HashMap<>(); for (Peer peer : fleet) { peerOf.put(peer.name(), peer.node().peerId()); } assertThat(coordinator.issues().readAllIssued(Template.of(CodeChange.class), 100)) .isNotEmpty() .allSatisfy(issued -> { assertThat(issued.issuer().localName()).isEqualTo("coder"); assertThat(issued.issuer().peer()).isEqualTo(peerOf.get(issued.entry().byAgent())); assertThat(issued.attestation()) .isEqualTo(ai.badmonkey.agentspaces.api.space.Space.Attestation.AGENT_ATTESTED); });
identity::subordinate for a fixed certificate of one hour. Code Fleet uses renewingSubordinate, which keeps one key and re-issues its certificate at half-life, so a coder that runs for days never outlives it. Receivers judge each certificate at the moment of signing, so old results stay verifiable.When a worker dies
The demo kills the sweeper by configuration. runCoder takes a dieAfter count, and the sweeper's is 2. When its third take starts, code() closes the coder's own binding and throws. The binder catches the exception, logs a warning, and never completes the take. The peer, its replica and its gossip keep running: what dies is the agent, and the agent is what held the lease. Before it closes, the coder records the issue it holds in abandoned, which is how the demo's closing lines and the test name the orphan.
@SpaceTake(space = ISSUES, lease = "5s", pollTimeout = "2s", resultLease = "1h") public CodeChange code(Issue issue) { if (dieAfter >= 0 && done >= dieAfter) { // Crash mid-take: stop this agent and abandon the held issue. The // binder never completes a take whose action threw, so the 5 s lease // lapses and the issue reappears for another coder. abandoned = issue; close(); throw new IllegalStateException(label + " died mid-take"); } double cost = costModel.applyAsDouble(issue); sleep(300); // the coding work // Still the holder? A lower bid can reach this replica after our settle // window and displace the claim. renew throws LeaseExpiredException then, // so a displaced coder writes no review copy and no result, and the // binder logs the failed action and returns the coder to its take loop. TakeContext.current().ifPresent(TakeContext::renew); CodeChange change = new CodeChange(issue.issueId(), issue.area(), label, cost); changes.write(change, Lease.of(Duration.ofHours(1))); // for review done++; return change; // completes the take with the change as its result }
Nothing in the app detects the failure or hands the work on. The claim carries a 5 s expiry from the moment the coder made it. When the expiry passes, the issue is claimable again at the next epoch, and the coders that are still alive run the auction again. The only bidders left for an infra issue are the specialists, who both price it at 9 per unit. The 24 that the sweeper would have charged became 36.
These are the lines of the trace behind the picture, verbatim from the same run. The sweeper completed ISSUE-2 at 1470 ms, claimed ISSUE-8 at 1482 ms, and said nothing more. The second claim reached the coordinator 5006 ms later, from a specialist, at the 36 both specialists priced. The backend coder completed it, and the CI result for ISSUE-8, the last of the nine, landed at 7387 ms.
616 ms bid backend prices ISSUE-8 (infra, d4) at 36.0 617 ms bid sweeper prices ISSUE-8 (infra, d4) at 24.0 621 ms bid frontend prices ISSUE-8 (infra, d4) at 36.0 1470 ms issues COMPLETED ISSUE-2 by coder-sweeper/coder 1477 ms issues WRITTEN CodeChange ISSUE-2 cost 18.0 byAgent coder-sweeper 1482 ms issues TAKEN ISSUE-8 by coder-sweeper/coder 6488 ms issues TAKEN ISSUE-8 by coder-frontend/coder 7049 ms changes WRITTEN CodeChange ISSUE-8 by coder-backend/coder 7061 ms issues COMPLETED ISSUE-8 by coder-backend/coder 7068 ms issues WRITTEN CodeChange ISSUE-8 cost 36.0 byAgent coder-backend 7075 ms changes TAKEN CodeChange ISSUE-8 by review-a/reviewer 7387 ms changes WRITTEN CiResult ISSUE-8 passed=true 7396 ms changes COMPLETED CodeChange ISSUE-8 by review-b/reviewer 7401 ms changes WRITTEN Review ISSUE-8 review-b LGTM
In the recorded demo the same shape produced a different winner: ISSUE-8 went to the frontend coder at 36. The two specialists bid the same, so the tie goes to the lower stamp, and which coder's stamp is lower depends on timing. Both outcomes are correct, and a test that asserted one of them would be a flaky test. The warning the binder logs is the visible mark of the death:
WARNING: coder.code: action failed; lease will lapse java.lang.IllegalStateException: coder-sweeper died mid-take
What to watch for
- The lease is the recovery time. The fleet waited 5 s for an issue that was never in progress. A shorter lease recovers faster. The price is that a job longer than the lease starts to look dead while it still works.
- A displaced worker stops at its renew. If another claim replaced the holder's, the holder's renew throws a lease error, so it writes no copy for review and the binder has no completion to attempt. Before the check existed, the copy stayed in the changes space. The few milliseconds between the renew and the completion stay open, and counting distinct issue ids covers them.
- Long jobs renew. The 300 ms job here fits its lease with room to spare, and the app calls
TakeContext.current().ifPresent(TakeContext::renew)once, as the displacement check. A coder that works for minutes can call it as it goes, which extends the take lease by the binding's lease each time. - Recovery has a price. The fleet paid 36 for work priced at 24 and took about 5 extra seconds to finish. It chose to pay, which is the trade the README describes: a higher price keeps the migration moving.
Running and testing it
The project is a standalone Maven build. It needs JDK 21 and the AgentSpaces 0.6.0 libraries, which resolve from Maven Central, and it needs no API key.
cd agentspaces-code-fleet mvn test # the flow test over real TCP: 1 test, about 9 seconds ./run-demo.sh # the demo: nine issues, one worker dying, all CI green
The demo listens on the fixed ports 7571 to 7576, so two copies at once collide. The test asks the operating system for a free port per peer and runs beside anything else. The script is one line, mvn -q compile exec:java. The pom declares 6 AgentSpaces modules, all at the one version property below, and two test libraries (junit-jupiter, assertj-core).
<properties> <maven.compiler.release>21</maven.compiler.release> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <agentspaces.version>0.6.0</agentspaces.version> <junit.version>5.13.4</junit.version> <assertj.version>3.27.7</assertj.version> </properties>
What the flow test asserts
There is one test, everyIssueIsAllocatedReviewedAndPassesCiDespiteAWorkerDying. It starts the six peers over real TCP, binds the agents, waits 1.5 seconds for the group to settle, writes the 9 issues, and then asserts in order. The picture lists the assertions and, on the right, what they leave unproven. The CI wait and the allocation check both count distinct issue ids, and the sweeper assertions read the Coder that runCoder returns.
// Every issue eventually produces an approved change that passes CI, // even though the sweeper dies after two changes. The check is on // distinct issue ids, so a duplicate CiResult cannot stand in for a // missing issue. Set<String> expected = new TreeSet<>(); for (int i = 1; i <= issueCount; i++) { expected.add("ISSUE-" + i); } List<CiResult> ci = awaitCi(coordinator, issueCount, Duration.ofSeconds(120)); assertThat(ci.stream().map(CiResult::issueId).collect(Collectors.toSet())).isEqualTo(expected); assertThat(ci).allSatisfy(r -> assertThat(r.passed()).isTrue()); // Every issue was allocated: the AUCTION completions land in the issues // space as CodeChange result entries (the changes space copies are taken // and consumed by review, becoming Review entries). Await them settling. List<CodeChange> changes = awaitAllocations(coordinator, issueCount, Duration.ofSeconds(30)); Set<String> changedIssues = changes.stream().map(CodeChange::issueId) .collect(Collectors.toSet()); assertThat(changedIssues).isEqualTo(expected);
// The swarm distributed the work: more than one agent produced changes, // and the crashed sweeper produced at most the two it managed before dying. long sweeperChanges = changes.stream() .filter(c -> c.byAgent().equals("coder-sweeper")).count(); assertThat(sweeperChanges).isLessThanOrEqualTo(2); Set<String> agentsThatWorked = changes.stream().map(CodeChange::byAgent) .collect(Collectors.toSet()); assertThat(agentsThatWorked).hasSizeGreaterThanOrEqualTo(2);
// The sweeper died, and its work came back: it crashed holding an issue // (nobody else could have made it), its lease lapsed, and another coder // completed that issue and passed CI. assertThat(sweeperCoder.died()).as("the sweeper reached its third take and died").isTrue(); String orphan = sweeperCoder.abandoned().issueId(); assertThat(changes).filteredOn(c -> c.issueId().equals(orphan)) .isNotEmpty() .allSatisfy(c -> assertThat(c.byAgent()).isNotEqualTo("coder-sweeper")); assertThat(ci).extracting(CiResult::issueId).contains(orphan);
// Attribution is evidence: every change's declared author is // its authenticated issuer, and every change is signed by that agent's own // certified key. java.util.Map<String, ai.badmonkey.agentspaces.common.id.PeerId> peerOf = new java.util.HashMap<>(); for (Peer peer : fleet) { peerOf.put(peer.name(), peer.node().peerId()); } assertThat(coordinator.issues().readAllIssued(Template.of(CodeChange.class), 100)) .isNotEmpty() .allSatisfy(issued -> { assertThat(issued.issuer().localName()).isEqualTo("coder"); assertThat(issued.issuer().peer()).isEqualTo(peerOf.get(issued.entry().byAgent())); assertThat(issued.attestation()) .isEqualTo(ai.badmonkey.agentspaces.api.space.Space.Attestation.AGENT_ATTESTED); });
/** Awaits CI results for {@code distinctIssues} different issues, counting issues, not entries. */ private static List<CiResult> awaitCi(Peer peer, int distinctIssues, Duration timeout) throws InterruptedException { long deadline = System.nanoTime() + timeout.toNanos(); List<CiResult> ci = List.of(); while (System.nanoTime() < deadline) { ci = peer.changes().readAll(Template.of(CiResult.class), 100); long distinct = ci.stream().map(CiResult::issueId).distinct().count(); if (distinct >= distinctIssues) { return ci; } Thread.sleep(250); } return ci; }
On 2026-11-04 at AgentSpaces 0.5.0 the test passed three times, in 9.11, 9.45 and 9.25 seconds of test time and about 10.0 to 10.2 seconds for the whole Maven build. The stack trace in the output is the sweeper's deliberate crash. The test proves what its assertions say: CI passed for nine distinct issues with a worker configured to die, nine distinct issues have a completed change, no more than two changes came from that worker, the work was shared between at least two coders, the sweeper died and the issue it held was completed by another coder that passed CI, and the agent key that signed each change is the author the change names. It does not assert the price or the delay of the re-run, that each winner was the lowest bidder, or that no duplicate was ever written, because both distinct-id checks tolerate one. The sweeper assertion needs the sweeper to reach a third take. It does so in practice, because nine issues keep three coders busy for about three waves, and a run in which it never did would fail on the assertion that the sweeper reached its third take and died.
Where to go next
The developer guide covers the parts this app uses: @BidFunction and @SpaceTake for the annotations, conflict strategies for LEASE_RACE and AUCTION, leases, agent certificates for the per-agent keys, and the example apps for the other example apps. The workflow guide has a short chapter on routing by cost and one on the two failure models. The Party Bus guide puts an auction beside a quorum vote and an ordered log, and the Superfriends guide runs three model frameworks in one fleet.
Where to take it
- Real models behind the same contract. Replace the sleep in
code()with a model call that returns aCodeChange. The bid function is the seam for a real cost, latency and quality model per agent. - A rejection path. Let a rejected
Reviewwrite the issue back, so the cycle becomes propose, review, revise. - Cards for a console. Pass a
DiscoveryServicetoregister, and the five agent cards become visible to the fleet console and to planners. - Patches as artifacts. A
CodeChangecarries no diff today. With the content swarm that came in 0.5.0 (agentspaces-content), a coder can publish its patch as an artifact and put the root in the entry, and a reviewer fetches the bytes from every member that holds them. - A lapse counter. The traced run shows no
REAPPEAREDevent for ISSUE-8, because the re-claim landed before the lease sweep. A watcher that countsTAKENevents per issue is the dependable meter: a secondTAKENfor one issue marks one lapse, and the kill story becomes a number on a dashboard.