| Field | Value |
|---|---|
| Decision ID | ADR-064 |
| Initiative | unsorry Phase 3 — verifier capacity efficiency |
| Proposed By | unsorry maintainers |
| Date | 2026-06-17 |
| Status | Accepted |
In the context of the ADR-058 coordinated-submission model, where a --prove
agent in UNSORRY_SUBMIT_MODE=queue pushes a locally-verified proof to a
queued/prove/<goal>/<agent>-<hex> branch and a separate --dispatch-queue
loop later opens those branches as PRs under the submission governor,
facing a queue that had grown to 653 branches covering only 316 distinct
goals — 337 branches (52%) were duplicate goals and a further 26 goals were
already proved on main — so over half the namespace verifier capacity needed
to drain the queue would be spent on proofs that can never merge (first-merge
wins, ADR-004) and instead close as conflicts, exactly the #1924/#1925 pair we
observed; the duplication itself is the claim-race window ADR-017 knowingly left
unfixed (queued_prove_branch_exists is a non-atomic pre-check, so N agents
selecting the same top-ranked goal in one window all pass it and push distinct,
non-colliding branch names) compounded by claim-TTL expiry reopening goals whose
proofs sit undispatched — but ADR-017’s mitigation (the supervisor closing
duplicate PRs, keeping the oldest) never fires because queue-mode duplicates
are branches, not PRs,
we decided for moving the in-flight-work guard to the dispatch boundary: the
dispatcher opens at most one prove PR per goal per pass, skipping a queued
branch whose goal is already proved on main (authoritative library/index
marker read from freshly-fetched origin/main), already has an open prove PR
(open_prove_pr_exists), or was already handled earlier in the same pass (an
in-run seen-set) — non-destructively, so a goal’s sibling branches survive as
fallbacks until one of them merges,
and neglected (a) fixing the prove-time claim race itself — making the queued
branch race-safe (a fixed per-goal branch name so the second push loses on
non-fast-forward, or holding the claim live until dispatch/merge) — kept deferred
exactly as ADR-017 deferred it, because dispatch-level dedup already bounds the
cost to “verified-once-locally, dispatched-once”; and (b) bulk-deleting the
existing redundant branches, left as a separate operational cleanup since the
dispatcher now simply never opens them,
to achieve a dispatcher whose useful throughput is the goal-merge rate, not
the branch count — recovering the ~56% of verifier capacity previously burned on
unmergeable duplicates with no new runners,
accepting that the proved-on-main and open-PR checks are best-effort (a git
or gh error degrades to “not deduped” and the branch is dispatched, matching
ADR-017’s “selection must not depend on API health”), the in-run seen-set bounds
duplicates only within a single pass (cross-pass duplicates are caught by the
open-PR check once the first PR exists), and one extra git fetch origin main
runs per dispatch pass.
This ADR is the queue-era continuation of ADR-017. ADR-017 identified the
claim-race that produces duplicate proofs (#184/#185) and chose to bound its
cost via PR-level hygiene rather than fix the race. ADR-058 then changed where
duplicates land — from immediately-open PRs to dormant queued/prove/* branches
— which silently removed ADR-017’s bound: the supervisor’s duplicate-PR closer
operates on PRs, so branch-resident duplicates accumulated unchecked until the
dispatcher amplified them into PRs. ADR-064 restores the bound at the new
boundary (dispatch) instead of the old one (PR-open).
The change is confined to swarm/agent.sh’s dispatch_queue, reusing the
existing open_prove_pr_exists guard and adding a goal_already_proved check
plus a per-pass seen-set. Branch sourcing is factored into queued_branch_refs
and main-fetch into fetch_main_ref so the dedup is hermetically self-tested
(test_dispatch_goal_dedup).
Pros: smallest surgical change; reuses proven guards; non-destructive (siblings remain as fallbacks); recovers ~56% capacity immediately; same best-effort posture as ADR-017. Cons: does not stop the wasted prove compute upstream (the duplicate branches are still produced), only the wasted verify compute downstream.
Make queued-branch creation atomic per goal (fixed branch name, first-push-wins like the claims branch) or hold the claim live until dispatch. Pros: stops duplication at the source, saving prove compute too. Cons: larger change to the claim lifecycle (ADR-004/ADR-010) with its own race and overwrite hazards; deferred deliberately, as in ADR-017, because dispatch-level dedup already caps the cost. Tracked as the follow-up this ADR explicitly leaves open.
Delete a goal’s other queued branches once one is chosen. Pros: shrinks the visible queue. Cons: loses the fallback if the chosen proof fails Gate A; unnecessary, since a skipped branch is harmless and a separate GC can prune already-merged goals’ branches safely.
| Relationship | ADR ID | Title | Notes |
|————–|——–|——-|——-|
| Amends | ADR-017 | Swarm Supervisor and In-Flight-Work Guard | Extends the in-flight guard from the PR-open boundary to the dispatch boundary |
| Amends | ADR-058 | Runner Pool Segmentation and Verification Capacity | Makes --dispatch-queue open one PR per goal |
| Depends On | ADR-018 | Byte-Identity / index proved marker | library/index is the authoritative proved check |
| Relates To | ADR-004 | Claims Branch — First-Push-Wins | The unfixed claim race is the upstream cause |
| Relates To | ADR-010 | Affinity-Gap Selection | queued_prove_branch_exists pre-check is the racy guard |
| Reference ID | Title | Type | Location | |————–|——-|——|———-| | REF-1 | SPEC-064-A — Goal-level dispatch deduplication | Specification | specs/SPEC-064-A-Goal-Level-Dispatch-Deduplication.md |
| Status | Approver | Date | |——–|———-|——| | Proposed | unsorry maintainers | 2026-06-17 | | Accepted | unsorry maintainers | 2026-06-17 |