architecture: how a task gets from release to flag
- 62solver-library modules57,767 lines
- 2,079tests
- 463replay fixtures
- 9race-day handler files
- 10tool articles
counted from the repository at every build.
two diagrams of the non-web race machinery: the pieces and who talks to whom, then one challenge from its release to its last flag with every fallback path. each box names the real file or command; the section numbers (3.6, 7.7, ...) point into the capabilities page, which describes each part in full. every game-master call goes through gm.py, the one client; on race day autopilot and kickoff make nearly all of them (the solid arrows), and a lane fixer, helper or parent reaches it only for a hand guess or probe (dashed): fixers fix solve.py, autopilot submits for them.
the pieces
the game master is the only grader. every call to it goes through one client, gm.py, so the rate limit, the edge pin and the answer forms live in one place. the actors in the middle row never talk to each other directly: they read and write files under sessions/ through coord.py (claims, edit locks, intel rows, mail, the board), and every solver imports the same shared library, ctfkit.hlib.
tools/comp/kickoff.py(6.2): the release on the game master's clock. at t-5m it starts a headless fixer for every open non-web lane with none live (fixer_watch, 6.4); at t-65s it pins the cloudflare edge and samples the clock (3.6); at t-60s it archives the days before; at t-20s it warms the route and starts oneautopilot.pyslot per lane and a spare; from t-0.3s two warm sockets take turns sending the list call every 80ms, and the first non-empty answer becomes the plan and the live marker.tools/comp/autopilot.py: no model in the loop. a slot claims its lane's single, scaffoldschallenges/dayNN/<id>/withuv run newchal, runs the lane's newest solver on the single's downloaded bytes with no game-master call (the dry run), submits, and on correct runs the time trial and the mastery itself. anything short of correct: it banks the accepted fields, posts agapsrow (or an... is yours, autopilot did not get itrow with ahandlers.pydraft) and releases the claim; then it watches the challenge's solver files and re-runs a saved fix within about a second.- the lane fixer, one per lane:
coord.py wait-live --nexthands it its lane's work only. it fixes by savinghandlers.pyunder the challenge's edit lock (coord.py edit <id>, 7.8) and reads a failed timed run withuv run replay <run>. - helpers take work in no lane and assist a held single: one field family each (
coord.py take), fixes sent ascoord.py patch, offline replays of a failed timed run. - the parent never owns a task. it keeps one spawn watcher running (
coord.py spawn --wait), respawns a stopped fixer, and owns gm incidents. ctfkit.hlibholds the lane readers and their registries (decode.TRANSFORMS,forensics.PROPERTIES,apk.CODEC_ALIASES,compound.PRODUCERS,specimen),crosslane(a field one lane cannot name, read by another lane's reader of that exact name, 7.5), the fixes mailbox andrunner.run, the timed runner (7.2). it is frozen during the race: fixes go into the challenge's ownsolve.pyorhandlers.py.- replay and fixtures:
uv run dryrun <id>(a solver on today's bytes, field by field),uv run replayovertests/fixtures/(every graded run), and the night-before gate (tools/after-action/nightly.py, 6.5) that ends inautopilot.py --check. - dashboards and logs:
uv run dash,coord.py watchandcoord.py board,uv run timeline --day N(where the seconds went), andlogs/comp/session.logandlogs/comp/flags.jsonunderneath them.
a task from release to flag
the middle column is the path a clean day takes: the release, autopilot's claim and dry run, one submit, correct, and the two timed tiers from the same solver. the boxes beside it are the fallbacks, each one a separate mechanism with its own trigger.
who does what, by role (the process names are the ids coord.py prints):
| role | process | at the release | when fields miss | when a timed run fails | never |
|---|---|---|---|---|---|
| kickoff | tools/comp/kickoff.py, one per day |
pins the edge at t-65s, warms the route and starts one autopilot slot per lane at t-20s, sends the hedged list from t-0.3s, writes the plan and the live marker | nothing: it has exited | nothing | solves or submits an answer |
| autopilot | auto.<lane>, one slot per lane (tools/comp/autopilot.py), no model in the loop |
claims the single, scaffolds solve.py from the lane's newest solver, downloads the bytes, dry-runs the solver on them with no game-master call, and when every field is answered and confident submits once; on correct it starts the time trial and then the mastery itself |
submits what it has, banks the fields the grader accepts, posts a gaps row (each crash's file:line) or an is yours row (the question text, the closest readers, a handlers.py skeleton), releases the claim, then watches the solver files and re-runs a saved fix within about a second |
saves the run's bytes, re-solves the saved run with the fixer's fix, re-rolls the attempt at its deadline (at most twice) or plays the practice op | waits on a human or a model |
| lane fixer | <lane> fixer, one per lane, a model |
reads its lane brief before the release, then waits on coord.py wait-live --next |
takes the gaps / is yours row as its task: coord.py edit <id>, writes handlers.py (the computation that got the value is the rule), saves; autopilot submits for it; a value it already holds goes to gm.py guess at once |
uv run replay <run> on the saved bytes, fixes, saves; autopilot re-solves the live attempt |
starts a timed tier while autopilot owns the lane; works another lane |
| helper | <runner>.wN, a model |
idle until coord.py next hands it work in no solver lane, or an assist on a held single |
one field family nobody is doing (coord.py take), a coord.py patch to the owner, an offline replay of someone else's failed run |
the same, as an offline assist | a second copy of the owner's work |
| parent | <runner>.main, a model |
spawns the fixers from the printed prompts, runs the spawn watcher, keeps kickoff.py alive, then polls wait-live for assists only |
routes: makes sure a helper holds the tier and the cause is in intel; a value it reads it submits at once | reads the stall mail, respawns a fixer that was cut short, resolves a game-master incident | owns a task; re-derives a fixer's fix |
| plumbing | coord.py (claims, intel, mail, board, locks), gm.py (the one game-master client), ctfkit.hlib (the readers every lane shares) |
| fallback | trigger | what happens | where |
|---|---|---|---|
| gaps, then the fixer | a crash or an unsure field in the dry run | accepted fields banked, a gaps row with each crash's file:line, the claim released; the fixer saves handlers.py and autopilot re-runs it within about a second |
tools/comp/autopilot.py, 7.8, 7.9 |
| slow dry run | still running after 3s | autopilot posts that it is still searching and releases the claim; the search goes on and still submits | autopilot.early_handoff (10) |
| a probe-won single | anyone wins the single by hand with gm.py guess |
autopilot follows it and runs the tiers once solve.py reproduces every graded field; otherwise a located solver (hlib.locate, 7.7) or CHAIN WAITS ON solve.py for the fixer's edit |
7.7, 4.3 |
| a timed crash or rejection | a set crashes or a submit comes back incorrect | the run is saved under files/runs/<run>/; uv run replay <run> while the fixer fixes; the saved fix re-solves the live attempt's own bytes; past the deadline autopilot re-solves the saved run with the fix and runs the tier on a fresh attempt (a failure confined to one set of several is re-rolled at most twice a tier); a spent tier goes on as next_op: practice on the same bytes |
7.2, 8.2 |
| ranked start refused | the game master will not open a ranked attempt | the regular untimed pool (WARNING unranked attempt): no deadline, a wrong submit leaves the attempt open; the board marks it unranked and the end of day reruns it for a time |
gm.py start, ctfkit.hlib.runner |
| gm incident | the first 5xx on a timed start | no timed start goes out into it; every waiting solve.py checks its solver offline and keeps its claim; the parent fixes gm.py, proves it with tools/comp/preflight.py --incident, then coord.py incident resolve re-execs every waiting solver |
10 |
| rate-limit window | 429s inside the release minute | the window is per team and clears at the next :00; every process holds and resends then | 3.5 |
| fixer cut short | a fixer exits before its lane is done | coord.py stopped <name> frees the name; the spawn watcher prints it for a respawn with a resume note; with no parent alive, kickoff's fixer_watch launches tools/comp/fixer_launch.py |
6.4 |
| stall | 90s with no new grader-confirmed field | coord.py pivot <id> mails a state note and a fresh agent on the other runner starts from it with a different method; 25 rejected guesses a field; at 5 minutes coord.py check prints ceiling and the parent is mailed |
STALL_S, 4.3 |
{generated by a clanker}