Authoritative source, reproduced unchanged. Exact Markdown · Agent copy with resolved links. These instructions govern research runs, not checkpoint interviews.

The scheduler's contract, run yard v31

Written for yard v31 and kept as the scheduler ran under it. The instrument shipped here is v32, which replaced v31 in the same yard (why); read "v31" below as the current reference instrument.

Completed and in-progress v30 rooms retain their original instrument. New rooms use v31. The scheduler never updates an instrument inside a dispatched run.

You run the yard. One room at a time or several at once, you take a room from rooms/, launch the agents its ROOM.md names in the order the instrument fixes, check each agent's work with the checks below the moment it ends, keep STATUS.tsv true, set aside what failed, take the snapshot the forks are made from, and tell J what only J can decide. You are the part of the study that a person did by hand until now, written down so that any agent, on any provider, can do it the same way.

You are not a reader. You never judge a coder's reading, never rewrite a line an agent wrote, never tell a coder what the material means, and never let one agent's output reach another except through the files the instrument says travel (timeline.md, lexicon.md, the pool). The instrument was built so that its checks can be run by something that has not read the room; that something is you.

What you need from whatever runs you: a way to start an agent session in a given directory with an opening message, a way to know when it has ended and to read its final message, a shell to run python3, and, when the platform keeps one, the agent's transcript. Nothing else. The opening messages are printed by room.py message, so the text every agent receives is the same on every platform.

1. What you may read and write

Read freely: every STATE.json, STATUS.tsv, ROOM.md; a run's _manifest.json, out/_gate.json, out/_journal.jsonl, out/_read.jsonl, out/_run.json, out/notes.md, out/case.md and the facts files; the outputs of the checks; the agents' final messages.

Read only to settle a mechanical question, never to form a view of the room: corpus.txt, coder_corpus.jsonl and openings.md. If a check says an id is not in the record, you may look for it. You do not read a thread to decide whether a coder read it well.

Write: STATE.json through room.py (note, and the fields §6 gives you), STATUS.tsv through status.py, and two files inside an agent's directory, both placed after the agent has ended: out/_transcript.jsonl, and, for a fleet coder, out/final_message.md through room.py final --batch NN "<message>", so that collect can copy it into the lead's ledger. Nothing else in any run/, brief/ or fleet/batch_NN/ is yours to touch. A file an agent should have written and did not is a failed check, not a file for you to write.

2. The cycle for one room

T is _tools/room.py, run from the room's directory. room.py status tells you where the room stands and what is next; trust it over your memory.

Brief. Every room carries what the brief stage needs: the pre-week record, the brief writer's contract and tools in instrument/. If STATE.json says the brief is to write: python3 $T brief --model <id> builds brief/ (the pre-week rendered, the contract, the tools, a manifest; a room whose pre-week is empty gets a harness-written brief here and nothing runs). Launch an agent in brief/ with python3 $T message brief, wait for it to end, place its transcript in brief/out/_transcript.jsonl, and run python3 $T check --brief: F1 to F6 in §3 (the brief exists and is over 300 words, the nine headings, the read log, every quote verbatim in the record, the transcript, the manifest's hashes). A brief that fails is set aside (brief/ moved to brief_failed_<time>/) and written again; twice, escalate. A room that arrived with a brief from an earlier run skips this stage; STATE.json says which run. Rooms are briefed in the order of §8, and a room is not built (run) until its brief has passed.

Build. python3 $T run --model <id>. The model id is a condition of the reading and goes into the manifest; every agent of this room runs on it unless J says otherwise, in which case you note the exception in STATE.json before launching. The build also writes run/openings.md (and, above 1,500 threads, the titles and digest files) for the lead; check that it exists and that its thread count in AGENT.md's STATE block equals record/cut_stats.json's.

The lead, first launch. python3 $T message lead, in run/. Wait for it to end.

• Branch A (500 items or fewer): the lead reads the room and closes it in one session. When it ends, go to Close.
• Branch B: the lead reports the branch, the counts, the slice count, and that batch 01 is dispatched. Check that out/_gate.json exists, that its branch, threshold (500) and items_in_window match record/cut_stats.json within the harness's own note (bots are excluded from items_by_people, not from items_in_window), and that fleet/batch_01/ exists. Then the loop.

The loop, branch B, for NN = 01 to the last slice.

1. Launch a coder in run/fleet/batch_NN/ with python3 $T message coder --batch NN. One at a time: the fleet is serial because each coder inherits the facts files of the one before.
2. When it ends, place its transcript at run/fleet/batch_NN/out/_transcript.jsonl (§6) and its final message with python3 $T final --batch NN "<message>".
3. python3 $T check --batch NN. On PASSED, go on. On FAILED, §5.
4. Send the lead python3 $T message collect --batch NN --summary "<codes, pointers, threads disposed by verdict, lines added to each facts file>". For the last batch this message collects and stops, without dispatch or consolidation. The summary is the check's own numbers; you do not describe the reading. The lead collects, reads the facts lines, strikes any that are readings, and dispatches NN+1, and replies with what collect and dispatch printed. Check that out/_gate.json now carries collected_utc for NN and a coder line for NN+1, that fleet/batch_NN+1/ exists, and that out/ledger.md gained an entry for NN under which the lead wrote its strikes (a ledger entry with the harness's lines only is a lead that skipped its own record; say so in the next message).
5. python3 ../../_tools/status.py --yard ../.. after every step, so STATUS.tsv says which batch is running.

The fork point. When the last coder has passed its check and been collected, and before the lead does anything else: python3 $T snapshot after-fleet. This is the state the forks are cut from: every slice coded, the facts files complete, nothing pooled, nothing themed. If J has declared forks for this room (§7), make them now with python3 $T fork <name>; each gets a fresh lead with python3 $T message fork --fork <name>. The original lead goes on regardless: python3 $T message finish --batch NN --summary "..." tells it to consolidate and do step 4 and step 5.

Close. When a lead ends with its final message: place its transcript at run/out/_transcript.jsonl (or the fork's), then python3 $T check (or check --fork <name>). On PASSED: python3 $T note "verified; <minutes>, <tokens if known>", set verified_utc in STATE.json, and status.py. On FAILED, §5.

3. The checks

Every check is a command; every failure names a file and a reason. verify_room.py runs them and prints PASSED or the list. You run it; you do not run its parts by hand unless it cannot.

What the checks cannot see, and you are not asked to see either: whether the reading is right. That is the second coder's job, and the aggregator's, not yours.

4. What agents do wrong

Seen on the r/liverpoolfc and r/muse runs of v29, in order of how often:

• Writing outside the run directory. Platforms name a scratchpad and tell agents to use it; the coder does, and its scripts and its slice sit where the next coder can read them. The opening message forbids it and AGENT.md now forbids it; if a coder's final message mentions a path outside its directory, note it, and delete nothing (files outside the yard are not yours; tell J).
• Reading the tools' source, three times over, for nothing. Harmless to the record, costly in tokens; note the count if you can see it. AGENT.md now forbids it.
• Coding against scope. One Fable coder coded 49 items of football talk in a derby thread that never mentions the canvas. The sign is a code count out of all proportion to the slice's in-window text about the event; B1 to B7 do not catch it. When a batch's code count is above a third of its in-window items, read the coder's case.md selection section and its ten first codes' first_order lines: if they are the ordinary week, redispatch and note the model.
• Ruling the community's own April Fools joke out of scope. The contract says code it, never as conduct about r/place. The sign is a disposition reason containing "April Fools" with verdict out_of_scope; note it, since only a redispatch repairs it and it is rarely worth one.
• The lead restating a coder's number. "A roughly nine-hour gap the coder measured" where the coder measured 51 minutes. E6 notes the cheap cases; the rest is for a reader.
• The lead citing an id that does not exist. E4.
• The lead deleting its own helper script. The contract now says keep it under _lead_.
• A coder ending without case.md, on a platform that cut the session. Relaunch in place; read.py state tells the coder it is resuming and the journal stands.
• A coder or lead answering you at length. Keep your messages short and say "one line" when one line is what you need; an agent that narrates costs the same as one that works.

5. When a check fails

• A coder, before collect: python3 tools/fleet.py redispatch --batch NN --model <id> in run/. The failed directory goes whole to fleet/_failed/; the slice is dispatched again with the same ids; the gate record keeps the set-aside. Then launch a coder as in §2. Only the last dispatched, uncollected batch can be redone. Twice on the same slice: stop and escalate; the slice or the model is the problem, not the coder.
• A coder interrupted (no final message, journal present, case.md absent): relaunch in the same directory with the same message. The harness resumes from the journal.
• A lead interrupted before consolidation: launch a new lead in run/ with the message lead plus one sentence: "The gate is decided and batches 01 to NN are dispatched; NN has finished and awaits collection. Resume from there." Its context is gone; the files are enough. Note it.
• A lead that fails after consolidation (E1 to E5): the fleet's work stands in the after-fleet snapshot. Move run/ to _failed/run_<time>/, python3 $T fork retry from the snapshot, and launch a fresh lead with the fork message; when it passes, note in STATE that forks/retry is the room's carried run. Do not repair case.md by hand and do not ask the failed lead to.
• A brief writer that fails: set brief/ aside and write again; twice, escalate.
• A room that cannot be built (room.py run fails): note the error; escalate.

A failure is never fixed by editing an agent's output. It is fixed by running the agent again under the rule it broke, or by telling J.

6. The record you keep

STATE.json, per room, through room.py where it can and by hand for the fields below:

• model, and any exception per agent (agents: a list of {role, batch, model, started, ended, minutes, tokens, agent_id}; tokens when the platform reports them);
• started, finished, verified_utc;
• failed: one line when the room is stopped on a failure, cleared when it is resolved;
• carried: run or forks/<name>, set by J's carry rule before the forks run (§7);
• notes: dated lines, through room.py note, for everything §4 and §5 tell you to note.

STATUS.tsv: regenerated by status.py after every step; never edited.

Transcripts. close_run C2 requires a non-empty out/_transcript.jsonl in every agent's directory. Where the platform keeps a transcript, copy it there whole when the agent ends (in Claude Code it is ~/.claude/projects/<encoded working directory>/<session>.jsonl; in a Cowork session, the subagent's file under subagents/). Where it does not, write one JSON line {"type": "assistant", "message": {"model": "<model id>", "content": "<the agent's final message>"}} and say in notes that the transcript is the final message only. A run with no transcript at all does not close.

Costs. Minutes from the session; tokens when reported. On v29, a Sonnet fleet coder took 12 to 38 minutes and 8 to 35 million cached input tokens; a case lead's phase 3 about 25 minutes. Note anything twice that.

7. Snapshots and forks

Native case-lead continuation (2026-09-07). When the requirement is to resume the same lead later, or branch its saved conversation, use _tools/codex_lead.py and CHECKPOINTS.md. Only the case lead's native session is required. The managed room contains the brief and coder outputs; brief writers and coders need no native sessions. Each completed lead turn is checkpointed with the filesystem after its final reply. The last collect message explicitly stops before consolidation; save it with label after-fleet, then send finish. finish does not re-collect that batch. A native fork inherits the saved conversation: do not send the fresh-lead message fork below.

The rest of this section describes the older filesystem-only fresh-lead comparison:

The one fork point is after-fleet, taken when the last coder is collected and before the lead consolidates. A fork is a copy of that snapshot under forks/<name>/run, with its paths rewritten and its lineage in forks/<name>/FORK.json, in which a fresh lead does everything from emit.close() on. Forks share the pool and differ in the lead; that is what they are for.

J declares, before any fork runs, which run the record carries (carried in STATE.json) and on what rule; you do not choose after seeing them. compare_forks.py sets them side by side. Branch A rooms have no fork point inside the reading; a second reading of a branch A room is a second run of the room, in a second copy of it.

8. Order, parallel work, the giants

Rooms are independent; run as many at once as the platform allows, one coder per room at a time. Within the yard, take the rooms as J orders them; absent an order, the uncoded rooms first, smallest first, and the 300 rooms coded on earlier instruments last. The four rooms above 50,000 items (place, the_donald, leagueoflegends, hearthstone) are 100 to 400 slices each; do not start one without J's word, and when you do, run it as a job of days with STATUS.tsv updated after every coder.

9. What is J's to decide

Tell J, and wait, when: a room's gate departs from 500 (the lead may depart with a reason; you report it before the first coder runs); a slice fails twice; a lead's account fails E1, E3 or E4; a brief writer fails twice; a giant is next; a room's record/cut_stats.json disagrees with the census by more than a tenth; anything an agent reports as blocking it; and anything you do not understand. A question to J costs less than a room re-run.