Fix two real bugs in Tier 5 Swiss tournament found by belated review

A scripting accident crashed the original orchestration before Tier 5 got
the same independent verify+review every other tier received, so it shipped
self-graded. Dispatching two independent agents after the fact (a verifier
and an adversarial reviewer) found two real problems the self-grading
missed, plus one instance of an already-known bug class:

1. HIGH: a bye credited worlds.length x seeds x 2 (a maximum-margin sweep)
as pure wins with zero losses -- reproduced live tying a candidate that
structurally cannot fight with a genuine winner, and confirmed that
credit exceeded the best real margin observed across the project's own
strategy roster. Fixed: a bye now adds only to its own `byes` counter,
never wins/losses.

2. MEDIUM: pairRound's own comment and CLI text claimed a repeat pairing
only happens when every opponent has already been played. False --
fuzz-tested against a brute-force checker, the old greedy-no-backtracking
walk produced an avoidable repeat in 25-51% of realistic tournaments
(n=6..50), and the shipped "rematch avoidance" test only passed because
its hardcoded seed happened to be lucky. Fixed: pairRound now backtracks
(findMatching, budget-bounded) to find a genuine zero-repeat matching
whenever one exists. Re-verified at the same scales the review used:
990 rounds, zero avoidable repeats (down from 25-51%).

3. low: the difficulty-echo bug fixed elsewhere in runDuel existed twice
more, unpatched, in runSwissBracket/runRoundRobinSwapped's own
bracket-level field.

Also corrects the search ledger's 2026-08-03 Swiss row, which repeated the
original implementation's false "rematches avoided" claim -- the ledger
now records what actually happened, including the correction itself.

1893 -> 1897 tests.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XsmxiQ6BxmWQRAF6BGjZTn

docs/odyssey-ai-review.md

@@ -627,5 +627,6 @@ re-run.
 | 2026-08-03 | a fair `duel` command (`tools/ailab.js`) can be built directly on the self-play refactor, reusing `engine/victory.js`'s own resolution rather than inventing one | `pinnedDuelDials()` reads difficulty once into one object both sides spread from; `runDuel`/`runRoundRobin` | 1860→1867 (7 new tests). Independent review found a **second real high-severity bug**: `duel` always seated candidate A as `"player"` and B as `"ai"`, so on a world with a map-baked `asym` block (`oort`, `nimbus`) the fixed side decided the match — two *identical* candidates measured 6W-0L on oort and 1W-5L on nimbus. Fixed by alternating `swapAsym` by replicate parity; the same repro then measured 4-2 / 3-3, consistent with ordinary variance | **yes** |
 | 2026-08-03 | side-swap (both candidates play both owner slots) and never-blended difficulty brackets close the remaining "is one owner slot structurally easier" and "does averaging across difficulty hide an APM-driven edge" gaps `duel` alone couldn't rule out | `runSwappedDuel`/`runDuelBrackets`/`runRoundRobinSwapped`, side-swap on by default (no opt-out flag, "not an opt-in easy to forget") | 1867→1875 (8 new tests). Review found only non-blocking issues (a cosmetic aggregate-level difficulty-echo bug carried over from `duel`, and a documented note that the two swap directions sample different seeds so a disagreement between them isn't *purely* an owner-slot signal) — no fix cycle needed, passed on first review | **yes** |
 | 2026-08-03 | `search`'s existing coordinate-scan can evaluate candidates by tournament standing instead of solo `score()` against a scripted bot, without changing the scan mechanics or the non-tournament path | `--tournament-against baseline.json` switches `evaluate()` to `runDuelBrackets` against a fixed baseline; `mode`/`detail` shape distinguishes tournament rows from score rows | 1875→1880 (5 new tests). Verifier independently re-ran `runDuelBrackets` on `search`'s own winning candidate and diffed against `search`'s internal result — byte-identical, proving genuine delegation rather than a look-alike calculation. One cosmetic-only finding (an advisory CLI line unconditionally reworded) | **yes** |
-| 2026-08-03 | Swiss pairing (closest-standing pairs, rotated byes, `max(3, ⌈log₂n⌉)` rounds) is the right bounded Tier 5 slice — not an ELO ladder (needs cross-invocation persistence this project has no use for yet) or Odyssey multi-owner (needs the refactor generalized past two slots, out of proportion for a scheduling layer) | `runSwissTournament`, reusing `runSwappedDuel` unchanged as the per-pairing primitive | 1880→1893 (13 new tests). Independently verified live: a deliberately lopsided field's strong candidate rose to the top of standings; byes rotated rather than always landing on the same candidate; rematches avoided while a fresh opponent remained | **yes** |
-| 2026-08-03 | the difficulty-echo bug found (and left, as non-blocking) during the side-swap review also exists one level up, in `runDuel`'s own aggregate return, not just the per-pairing summaries built on it | `runDuel` now returns `dials.difficulty` (the normalized value every row already used) instead of the raw, unvalidated `difficulty` parameter | Confirmed live: `--difficulty totallyBogusTypo` previously reported `difficulty: "totallyBogusTypo"` at the aggregate level while every row correctly showed `"medium"`; now the aggregate reads `"medium"` too. `runSwappedDuel`/`runDuelBrackets` inherit the fix for free (they read `.difficulty` off `runDuel`'s result). No behavior change for any valid difficulty string | **yes** |
+| 2026-08-03 | Swiss pairing (closest-standing pairs, rotated byes, `max(3, ⌈log₂n⌉)` rounds) is the right bounded Tier 5 slice — not an ELO ladder (needs cross-invocation persistence this project has no use for yet) or Odyssey multi-owner (needs the refactor generalized past two slots, out of proportion for a scheduling layer) | `runSwissTournament`, reusing `runSwappedDuel` unchanged as the per-pairing primitive | **Correction below (same date) — this row's own "independently verified" claim was false; see the next row.** A scripting accident in the orchestration crashed before Tier 5 got the same independent verify+review every other tier in this table got; it shipped self-graded (1880→1893, 13 new tests, all green) with nobody else checking it first | **partially — see below** |
+| 2026-08-03 | the row above claimed independent verification Tier 5 never actually received — dispatched two fresh, independent agents (a verifier and an adversarial reviewer, same as every other tier) after the fact to check it for real | — | Both found real problems the self-grading missed. **(1) HIGH:** a bye credited `worlds.length × seeds × 2` (a maximum-margin sweep) as pure wins with zero losses — reproduced live tying a candidate that structurally cannot fight (`neverInitiates` + a zero standing-army cap) with a genuine winner, and confirmed that credit exceeded the best real margin observed across every pairing of the project's own 4 named strategies (best real: 7/8; bye credit: 8/8). **(2) MEDIUM:** the pairing algorithm's own comment and CLI text claimed a repeat pairing only happens when "every remaining opponent has already been played" — false: fuzz-tested against a brute-force ground-truth checker, a plain greedy walk (first-fit, no backtracking) produced an *avoidable* repeat in 25-51% of realistic tournaments at n=6..50, and the shipped "rematch avoidance" test only passed because its hardcoded `seedBase` (7) happened to be lucky (6/9/10 reproducibly failed). **(3) low:** the same difficulty-echo bug class fixed elsewhere that day existed twice more, unpatched, in `runSwissBracket`/`runRoundRobinSwapped`'s own bracket-level field | **yes — this is what the row above should have said** |
+| 2026-08-03 | fix all three, properly this time: a bye must be worth nothing, and rematch-avoidance must actually hold, not just usually | Bye: removed the wins credit entirely — a bye now adds only to its own `byes` counter, never `wins`/`losses` (renamed `byePoints`→`byeMatchCount`, kept as informational-only). Pairing: `pairRound` now backtracks (`findMatching`, bounded by `MATCH_ATTEMPT_CAP`) to find a genuine zero-repeat matching whenever one exists, falling back to the old greedy pass (which allows repeats) only when none does. Difficulty echo: both remaining instances now read through `pinnedDuelDials` | Fuzz-verified the pairing fix at the exact scales the review found failing (n=4..50, realistic sequential simulation, 990 rounds total): **0 avoidable repeats**, down from the review's measured 25-51%. The bye fix directly closes the reviewer's own repro (a non-fighting candidate can no longer tie a genuine winner). Full suite 1893→1897 (new: a direct backtracking-vs-greedy regression test reproducing the reviewer's exact stranding scenario, a genuine-impossibility fallback test, the bye-neutrality tests, and a strengthened rematch-avoidance test run across 5 seed bases including the ones that broke the old algorithm) | **yes** |

test/ailab.test.js

@@ -26,7 +26,7 @@ import { join } from "node:path";
 import {
   run, labWorld, summarise, score, applyOverrides, CHECKS, OPPONENTS, WORLDS, WEIGHTS, runLeaderboard,
   runDuel, runRoundRobin, pinnedDuelDials, runSwappedDuel, runDuelBrackets, runRoundRobinSwapped, runSearch,
-  runSwissTournament,
+  runSwissTournament, pairRound,
 } from "../tools/ailab.js";
 import { STRATEGIES } from "../engine/aiStrategy.js";
 import { DIFFICULTY_OPTIONS } from "../engine/aiDifficulty.js";
@@ -768,41 +768,108 @@ test("byes rotate: nobody gets a second bye while another candidate hasn't had o
   assert.equal(new Set(byes).size, 5, `every candidate should get exactly one bye across 5 rounds of 5, got: ${byes.join(", ")}`);
 });
 
-test("a bye is worth a real pairing's own match count, not an arbitrary point", () => {
+test("a bye is scorable-neutral: it adds to nobody's wins or losses, only its own bye count", () => {
+  // A bye is a candidate the schedule couldn't pair, not a match anyone won — crediting it as a
+  // win (at ANY size) lets a candidate that never fights outrank one that actually won something.
+  // The only thing a bye should move is `byes` (bookkeeping/reporting), never `wins`/`losses`.
   const candidates = Array.from({ length: 3 }, (_, i) => ({ name: `C${i}`, strategy: "default" }));
   const opts = shortSwiss({ worlds: ["ferros", "vesper"], seeds: 2 });
   const [bracket] = runSwissTournament(candidates, opts);
-  const expected = opts.worlds.length * opts.seeds * 2;   // side-swapped -> both directions
-  assert.equal(bracket.byePoints, expected, "byePoints must equal worlds.length * seeds * 2, the n a real pairing would produce");
   const round = bracket.roundsLog.find(r => r.byeName);
   assert.ok(round, "fixture: an odd pool must produce a bye somewhere");
-  assert.equal(round.byePoints, expected);
-  if (round.matches.length) assert.equal(round.matches[0].n, expected, "a real pairing's own match count must match the bye's credit");
+  // byeMatchCount is purely informational — "how big a real pairing this round would have been" —
+  // and must still be reported accurately, just never added to anyone's standing.
+  const expectedMatchCount = opts.worlds.length * opts.seeds * 2;
+  assert.equal(bracket.byeMatchCount, expectedMatchCount);
+  assert.equal(round.byeMatchCount, expectedMatchCount);
+});
+
+test("a bye never lets a candidate that structurally cannot fight tie or beat one that actually won", () => {
+  // The exact scenario an independent review found broken: an odd field where one candidate is
+  // neverInitiates + a zero standing-army cap (cannot ever field a fight in skirmish) draws a bye,
+  // and a genuine winner must still rank strictly above it — a bye must never be worth what a real
+  // win is worth.
+  const normal = { name: "normal", strategy: "default" };
+  const crippled = (i) => ({
+    name: `crippled${i}`, strategy: `labByeCrippled${i}`,
+    overrides: { strategies: { [`labByeCrippled${i}`]: { neverInitiates: true, standingArmyCap: 0 } } },
+  });
+  // 3 candidates (odd): normal beats one crippled candidate in a real match, the OTHER crippled
+  // candidate draws the round's bye and therefore never fights anyone at all.
+  const candidates = [normal, crippled(1), crippled(2)];
+  const opts = shortSwiss({ worlds: ["korrath"], minutes: 15, seeds: 1, rounds: 1 });
+  const [bracket] = runSwissTournament(candidates, opts);
+  const byeRecipient = bracket.roundsLog[0].byeName;
+  assert.ok(byeRecipient, "fixture: 3 candidates is odd, a bye must fire");
+  const byeRow = bracket.standings.find(s => s.name === byeRecipient);
+  const normalRow = bracket.standings.find(s => s.name === "normal");
+  assert.equal(byeRow.wins, 0, "a candidate that never fought must have zero wins, bye or not");
+  assert.ok(normalRow.wins > byeRow.wins,
+    `the genuine winner (${normalRow.wins} wins) must rank strictly above a bye recipient that never fought (${byeRow.wins} wins)`);
 });
 
 test("rematch avoidance: with enough candidates relative to rounds, no pairing repeats", () => {
+  // A plain greedy pairing (this test's first version) could strand two candidates together even
+  // when a full zero-repeat matching existed elsewhere in the round — independent review found it
+  // failing 25-51% of the time at these exact scales, and that this very test only passed because
+  // its hardcoded seedBase (7) happened to be a lucky one (seedBases 6, 9, 10 reproducibly failed
+  // with the old algorithm). pairRound now backtracks to find a zero-repeat matching whenever one
+  // exists, so this checks across several seed bases — including the ones independently confirmed
+  // to break the old algorithm — rather than trusting a single roll.
   const candidates = Array.from({ length: 6 }, (_, i) => ({ name: `C${i}`, strategy: "default" }));
-  const [bracket] = runSwissTournament(candidates, shortSwiss({ rounds: 3 }));
-  const seen = new Set();
-  for (const { matches } of bracket.roundsLog) {
-    for (const res of matches) {
-      const key = [res.aName, res.bName].sort().join("::");
-      assert.ok(!seen.has(key), `pairing ${key} repeated across rounds even though unplayed opponents remained (6 candidates, 3 rounds)`);
-      seen.add(key);
+  for (const seedBase of [1, 6, 7, 9, 10]) {
+    const [bracket] = runSwissTournament(candidates, shortSwiss({ rounds: 3, seedBase }));
+    const seen = new Set();
+    for (const { matches } of bracket.roundsLog) {
+      for (const res of matches) {
+        const key = [res.aName, res.bName].sort().join("::");
+        assert.ok(!seen.has(key),
+          `seedBase=${seedBase}: pairing ${key} repeated across rounds even though unplayed opponents remained (6 candidates, 3 rounds)`);
+        seen.add(key);
+      }
     }
   }
 });
 
-test("Swiss standings: total wins minus total losses equals the bye credit handed out, nothing else", () => {
+test("pairRound backtracks to a zero-repeat matching a plain greedy walk would miss", () => {
+  // The exact failure an independent review reproduced: greedily pairing the two joint leaders
+  // first strands the round's one forbidden pair together, even though pairing either leader with
+  // one of them instead leaves a perfectly valid zero-repeat matching for the rest. Tested directly
+  // against pairRound on synthetic standings — fast, and isolates the pairing algorithm from match
+  // simulation entirely.
+  const standings = [
+    { name: "Aggressive", wins: 3, losses: 1 }, { name: "QuickCommit", wins: 3, losses: 1 },
+    { name: "Adaptive", wins: 1, losses: 3 }, { name: "ForceParity", wins: 1, losses: 3 },
+  ];
+  const played = new Set(["Adaptive::ForceParity"]);
+  const { pairs } = pairRound(standings, played, new Set());
+  const pairKeys = pairs.map(([a, b]) => [a.name, b.name].sort().join("::"));
+  assert.equal(pairs.length, 2, "4 candidates must produce 2 pairs");
+  assert.ok(!pairKeys.includes("Adaptive::ForceParity"),
+    `pairRound repeated the one forbidden pair even though a zero-repeat matching existed: got ${pairKeys.join(", ")}`);
+});
+
+test("pairRound still completes (with a forced repeat) when a zero-repeat matching is genuinely impossible", () => {
+  // 4 candidates who have all already played each other (a fully round-robin'd played-set) leave
+  // no zero-repeat option anywhere — pairRound must still return a complete pairing (via its
+  // greedy fallback) rather than hang or throw.
+  const standings = ["A", "B", "C", "D"].map(name => ({ name, wins: 0, losses: 0 }));
+  const played = new Set(["A::B", "A::C", "A::D", "B::C", "B::D", "C::D"]);
+  const { pairs } = pairRound(standings, played, new Set());
+  assert.equal(pairs.length, 2, "must still produce a complete pairing even with no zero-repeat option");
+  const paired = new Set(pairs.flatMap(([a, b]) => [a.name, b.name]));
+  assert.equal(paired.size, 4, "every candidate must appear in exactly one pair");
+});
+
+test("Swiss standings: total wins equal total losses — a bye contributes to neither", () => {
   // Every REAL pairing is win/loss-balanced (one side's win is the other's loss, exactly like
-  // round-robin's own invariant) — a bye is the only source of a win with no matching loss.
+  // round-robin's own invariant), and a bye is now scorable-neutral (previous test) — so unlike a
+  // points-based Swiss ladder, there is no unmatched credit anywhere in these standings at all.
   const candidates = Array.from({ length: 5 }, (_, i) => ({ name: `C${i}`, strategy: "default" }));
   const [bracket] = runSwissTournament(candidates, shortSwiss());
   const totalWins = bracket.standings.reduce((s, c) => s + c.wins, 0);
   const totalLosses = bracket.standings.reduce((s, c) => s + c.losses, 0);
-  const byeCredit = bracket.roundsLog.filter(r => r.byeName).length * bracket.byePoints;
-  assert.equal(totalWins - totalLosses, byeCredit,
-    "the only win with no corresponding loss anywhere is a bye's own credit");
+  assert.equal(totalWins, totalLosses, "every win must have a matching loss somewhere — a bye must add to neither");
 });
 
 test("standings are sorted most-wins-first (ties broken by fewer losses)", () => {
@@ -841,6 +908,27 @@ test("--difficulties (plural) runs an independent Swiss tournament per difficult
     "the two difficulty brackets must be independently-run tournaments, not one relabelled as two");
 });
 
+test("an unknown difficulty is normalized everywhere it's reported, not just where matches run: duel, round-robin, Swiss", () => {
+  // pinnedDuelDials() already normalizes an unknown/typo'd difficulty to "medium" for apm/micro,
+  // and every match row reports that normalized value — but three separate top-level aggregate
+  // fields each independently echoed the raw input instead: runDuel's own return, and (found by a
+  // later independent review of this same difficulty-echo bug CLASS) runRoundRobinSwapped's and
+  // runSwissBracket's per-bracket `.difficulty` field. All three must agree with what actually ran.
+  const a = { name: "A", strategy: "default" }, b = { name: "B", strategy: "aggressive" };
+  const c = { name: "C", strategy: "economic" };
+  const short = { worlds: ["ferros"], seeds: 1, minutes: 3 };
+  const bogus = "totallyBogusTypo";
+
+  const duelRes = runDuel(a, b, { ...short, difficulty: bogus });
+  assert.equal(duelRes.difficulty, "medium", "runDuel's aggregate difficulty must be normalized, not the raw input");
+
+  const [rrBracket] = runRoundRobinSwapped([a, b, c], { ...short, difficulty: bogus });
+  assert.equal(rrBracket.difficulty, "medium", "runRoundRobinSwapped's bracket difficulty must be normalized, not the raw input");
+
+  const [swissBracket] = runSwissTournament([a, b, c], { ...short, difficulty: bogus });
+  assert.equal(swissBracket.difficulty, "medium", "runSwissTournament's bracket difficulty must be normalized, not the raw input");
+});
+
 test("a Swiss tournament's overrides never leak into what runs next", () => {
   const before = JSON.stringify(STRATEGIES.aggressive);
   const candidates = [

tools/ailab.js

@@ -841,7 +841,10 @@ export function runRoundRobinSwapped(candidates, opts = {}) {
       A.wins += res.aWins; A.losses += res.bWins; A.draws += res.draws;
       B.wins += res.bWins; B.losses += res.aWins; B.draws += res.draws;
     }
-    return { difficulty: diff, pairs, standings: [...standings.values()].sort((x, y) => y.wins - x.wins) };
+    return {
+      difficulty: pinnedDuelDials(diff).difficulty,   // normalized — see pinnedDuelDials' own comment
+      pairs, standings: [...standings.values()].sort((x, y) => y.wins - x.wins),
+    };
   });
 }
 
@@ -862,24 +865,36 @@ export function runRoundRobinSwapped(candidates, opts = {}) {
    opts shape as runDuel/runRoundRobinSwapped. Tier 5 is a new SCHEDULE on top of a trusted
    primitive, not a new way of deciding who won a match.
 
-   PAIRING RULE (pairRound below): sort the field by current wins (ties keep the stable order
-   they arrive in — i.e. the standings Map's own insertion order, which starts as the input
-   candidate order), then walk down the sorted list pairing each candidate with the
-   highest-standing opponent it hasn't already played. That's the simplest version of the
-   standard Swiss "fold down on repeat" rule — deliberately not a full optimal-matching solver
-   (this bench already prefers "the simplest thing that works" — see the SEARCH header
-   comment above): a forced rematch only happens when every remaining opponent has already
-   been played, which small pools with many rounds can hit and large pools essentially never
-   do.
-
-   BYES: odd `candidates.length` leaves one player unpaired each round. It's awarded to the
-   LOWEST-standing candidate who hasn't had one yet (falling back to lowest-standing overall
-   once everyone has) — standard Swiss practice, and it keeps a bye from ever being handed to
-   the field's current leader. A bye counts as a full pairing's worth of wins (`byePoints`,
-   computed the same way a real pairing's match count would be: `worlds.length * seeds * 2`,
-   the exact `n` runSwappedDuel produces for that opts shape) — anything smaller would make a
-   bye worth less than a real result and distort the standings for the specific candidate the
-   schedule couldn't pair that round, which is not a judgement about their play.
+   PAIRING RULE (findMatching/pairRound below): sort the field by current wins (ties keep the
+   stable order they arrive in), then find a matching that avoids every already-played pair IF
+   ONE EXISTS. The first cut of this shipped as pure greedy — walk the sorted list, pair each
+   candidate with the first not-yet-played opponent remaining — and independent review caught
+   that it does NOT deliver the "avoids a repeat unless truly forced" guarantee it claimed:
+   fuzz-testing against a brute-force ground-truth checker measured avoidable repeats in roughly
+   a quarter to half of realistic tournaments (n=6..50), because a greedy walk can strand two
+   candidates with each other even when a full zero-repeat matching exists elsewhere in the same
+   round (classic "first fit with no lookahead" failure). findMatching now backtracks: for each
+   candidate (closest-standing first) it tries an unplayed opponent before ever trying a repeat,
+   and if that choice can't be extended into a complete matching for the rest of the pool, it
+   backtracks and tries the next one. Bounded by MATCH_ATTEMPT_CAP (small Swiss pools — this
+   tool's whole use case — resolve in a handful of attempts; the cap exists so a pathological
+   input can never hang) with a plain greedy pass as the last-resort fallback if the cap is hit,
+   so this always terminates and always returns a complete pairing.
+
+   BYES: odd `candidates.length` leaves one candidate unpaired each round. It's awarded to the
+   LOWEST-standing candidate who hasn't had one yet, falling back to lowest-standing overall once
+   everyone has — standard Swiss practice. That fallback CAN eventually reach the field's current
+   leader in a long-enough Swiss on a small pool (this tool's own default rounds formula keeps
+   real runs far short of that, but nothing prevents it if `--rounds` is pushed high). A bye is
+   NOT a win: it's the schedule's own bookkeeping for "this candidate wasn't paired," and the
+   first cut of this got that wrong too — it credited a bye as a full pairing's worth of wins
+   (`worlds.length * seeds * 2`, i.e. a maximum-margin sweep) with zero matching losses, which an
+   independent review caught letting a candidate that never fights at all tie or outrank one that
+   won a genuine match (reproduced live: a neverInitiates/zero-standing-army candidate that drew
+   a bye matched a real winner's standing). A bye now adds to nobody's `wins`/`losses` — only its
+   own `byes` counter — so standings reflect actual fighting, never schedule luck. `byeMatchCount`
+   is kept as an informational field only (how big a real pairing this round would have been),
+   never applied to anyone's tally.
 
    ROUNDS: default `Math.max(3, Math.ceil(Math.log2(candidates.length)))` — the textbook rule
    of thumb for how many Swiss rounds separate a field of that size — override with `--rounds`.
@@ -890,12 +905,63 @@ export function runRoundRobinSwapped(candidates, opts = {}) {
 
 const pairKey = (a, b) => [a, b].sort().join("::");
 
+// Total (candidate, opponent) trial attempts findMatching will spend across an ENTIRE call
+// (shared across all its recursive branches via the mutable `budget` object) before giving up
+// and falling back to a plain greedy pass. Small Swiss pools — this tool's whole use case —
+// resolve in well under this; it exists purely so a pathological input can never hang.
+const MATCH_ATTEMPT_CAP = 20000;
+
+// Backtracking search for a COMPLETE ZERO-REPEAT matching over `pool` (already sorted by
+// standing, closest-first) — every pair it considers must be absent from `played`; it never
+// accepts a repeat itself. For the pool's first member, tries each unplayed opponent in
+// closest-standing order, recursing on what's left; if a choice can't be extended into a
+// complete zero-repeat matching for the REST of the pool, it backtracks and tries the next
+// opponent — the step a plain greedy walk skips, which is exactly how it can strand two
+// candidates with each other (see the header comment above). Returns null — not a
+// repeat-containing matching — when no zero-repeat completion exists from here, so a caller
+// can tell "impossible" apart from "found one" and only then fall back to greedyMatching, which
+// is the one place a repeat is ever chosen. `budget.n` is decremented on every attempt and
+// shared across the whole recursion (mutated in place), so total work is bounded regardless of
+// tree depth; running out returns null the same as genuine impossibility, and the caller's
+// greedy fallback still always completes since repeats are unconditionally allowed there.
+function findMatching(pool, played, budget) {
+  if (!pool.length) return [];
+  const [a, ...rest] = pool;
+  for (const b of rest) {
+    if (played.has(pairKey(a.name, b.name))) continue;   // this search only ever considers UNPLAYED pairs
+    if (budget.n <= 0) return null;
+    budget.n--;
+    const remaining = rest.filter(c => c !== b);
+    const sub = findMatching(remaining, played, budget);
+    if (sub) return [[a, b], ...sub];
+  }
+  return null;   // no zero-repeat completion from here (or the budget ran out) — caller falls back
+}
+
+// The original greedy pass (closest-standing first, first not-yet-played opponent, forced repeat
+// if none remain) — kept only as findMatching's fallback if MATCH_ATTEMPT_CAP is ever exhausted,
+// so pairRound always terminates and always returns a complete pairing either way.
+function greedyMatching(pool, played) {
+  const rest = [...pool];
+  const pairs = [];
+  while (rest.length) {
+    const a = rest.shift();
+    let idx = rest.findIndex(b => !played.has(pairKey(a.name, b.name)));
+    if (idx === -1) idx = 0;
+    const b = rest.splice(idx, 1)[0];
+    pairs.push([a, b]);
+  }
+  return pairs;
+}
+
 // One round's pairings off the current standings, sorted highest-first. `played` is the set of
 // pairKey()s already run in ANY earlier round of this bracket; `hadBye` is the set of names
 // already given a bye. Returns { pairs: [[aRow, bRow], ...], byeName } — `pairs` holds the
 // standings rows (not the candidate objects; the caller looks the candidate up by name), so
-// this function stays pure and easy to test on plain data.
-function pairRound(standingsRows, played, hadBye) {
+// this function stays pure and easy to test on plain data. Exported for direct, fast unit tests
+// against synthetic standings/played-sets — the pairing algorithm's own correctness doesn't
+// depend on running real matches.
+export function pairRound(standingsRows, played, hadBye) {
   const order = [...standingsRows].sort((a, b) => b.wins - a.wins);
   let byeName = null;
   if (order.length % 2 === 1) {
@@ -904,34 +970,26 @@ function pairRound(standingsRows, played, hadBye) {
     if (idx === -1) idx = order.length - 1;   // everyone's already had one — lowest standing again
     byeName = order.splice(idx, 1)[0].name;
   }
-  const pairs = [];
-  const pool = order;
-  while (pool.length) {
-    const a = pool.shift();
-    let idx = pool.findIndex(b => !played.has(pairKey(a.name, b.name)));
-    if (idx === -1) idx = 0;   // every remaining opponent is a repeat — forced rematch, closest standing
-    const b = pool.splice(idx, 1)[0];
-    pairs.push([a, b]);
-  }
+  const pairs = findMatching(order, played, { n: MATCH_ATTEMPT_CAP }) || greedyMatching(order, played);
   return { pairs, byeName };
 }
 
 // One difficulty bracket's whole Swiss schedule: `numRounds` rounds of pairRound, each pairing
 // run through runSwappedDuel exactly like round-robin's own pairs — same opts shape, same
 // fairness. Standings accumulate match wins/losses/draws round over round, same tallying
-// runRoundRobinSwapped already does per pairing.
+// runRoundRobinSwapped already does per pairing; a bye adds only to `byes`, never `wins`/
+// `losses` — see the header comment above.
 function runSwissBracket(candidates, numRounds, opts) {
   const worlds = opts.worlds || ["korrath", "ferros", "vesper", "kybernet"];
   const seeds = opts.seeds ?? 2;
-  const byePoints = worlds.length * seeds * 2;   // == a real pairing's runSwappedDuel `n` — see header comment
+  const byeMatchCount = worlds.length * seeds * 2;   // informational only — == a real pairing's runSwappedDuel `n`
   const standings = new Map(candidates.map(c => [c.name, { name: c.name, wins: 0, losses: 0, draws: 0, byes: 0 }]));
   const played = new Set(), hadBye = new Set();
   const rounds = [];
   for (let round = 1; round <= numRounds; round++) {
     const { pairs, byeName } = pairRound([...standings.values()], played, hadBye);
     if (byeName) {
-      const row = standings.get(byeName);
-      row.wins += byePoints; row.byes += 1;
+      standings.get(byeName).byes += 1;   // NOT a win — see header comment
       hadBye.add(byeName);
     }
     const matches = [];
@@ -949,10 +1007,13 @@ function runSwissBracket(candidates, numRounds, opts) {
       B.wins += res.bWins; B.losses += res.aWins; B.draws += res.draws;
       matches.push(res);
     }
-    rounds.push({ round, byeName, byePoints: byeName ? byePoints : null, matches });
+    rounds.push({ round, byeName, byeMatchCount: byeName ? byeMatchCount : null, matches });
   }
   const standingsList = [...standings.values()].sort((x, y) => y.wins - x.wins || x.losses - y.losses);
-  return { difficulty: opts.difficulty, rounds: numRounds, byePoints, roundsLog: rounds, standings: standingsList };
+  return {
+    difficulty: pinnedDuelDials(opts.difficulty).difficulty,   // normalized — see pinnedDuelDials' own comment
+    rounds: numRounds, byeMatchCount, roundsLog: rounds, standings: standingsList,
+  };
 }
 
 // Swiss-paired tournament over `candidates`: `Math.max(3, Math.ceil(Math.log2(n)))` rounds by
@@ -1411,9 +1472,9 @@ const CMDS = {
     const brackets = runSwissTournament(candidates, swissOpts);
     for (const { difficulty, rounds, roundsLog, standings } of brackets) {
       console.log(`\n=== SWISS -- difficulty: ${difficulty} -- ${rounds} round(s), ${candidates.length} candidates ===`);
-      for (const { round, byeName, byePoints, matches } of roundsLog) {
+      for (const { round, byeName, matches } of roundsLog) {
         console.log(`\n-- round ${round} --`);
-        if (byeName) console.log(`  bye: ${byeName} (+${byePoints}, a real pairing's worth of match wins)`);
+        if (byeName) console.log(`  bye: ${byeName} (not paired this round -- no win/loss credit either way)`);
         for (const res of matches) { printSwappedDuel(res); console.log(); }
       }
       console.log(`SWISS STANDINGS (${difficulty})`);
@@ -1473,9 +1534,10 @@ const USAGE = `AI LAB — a headless bench for the Odyssey opponent.
                               pairing 'duel --candidates' uses, scheduled as SWISS rounds instead
                               of full round-robin, for candidate pools too large for C(n,2)
                               pairings to stay cheap. Default rounds: max(3, ceil(log2(n))). Each
-                              round pairs candidates by closest current standing and avoids a
-                              repeat pairing unless every other opponent has already been played
-                              -- see the TIER 5 header comment for the pairing/bye rules.
+                              round pairs candidates by closest current standing, backtracking to
+                              find a zero-repeat pairing whenever one exists rather than a repeat
+                              a greedy walk could've avoided -- see the TIER 5 header comment for
+                              the pairing/bye rules.
 
 Common flags
   --overrides f.json   inject candidate rows into the AI tables before running: