03
The relay types only when it is safe
Typed text and Enter answer what is on the screen. If the relay types at the wrong time, it can approve a command that nobody read.
- Before each message, and again before Enter, the relay checks four things. The session is not in a turn. No menu or trust question shows. The prompt has no text that a person left there. The screen stopped changing.
- Silence does not mean that a session is idle. Only a hook can tell the relay that a turn ended.
- A message is delivered only when a hook says that a turn started after it. If no hook comes, the relay tries again. Then it marks the session stuck and says why.
- The relay pastes text of 800 bytes or more in one piece. Claude Code reads typed text about 1024 bytes at a time and keeps only the last piece.
Code delivery.js · typed.js
Tests first-brief · review-typing · delivery-redraw
04
Each task gets its own checkout
Sessions that share one folder write over each other's work. Code that a session wrote must not reach your secrets or the work of another session.
- Each task, worker, reviewer and the PM gets its own checkout, on its own branch. Your folder does not change.
- Each task gets a stub
.env file. It has no real keys. It gives the task its own ports from 41000 to 41999, so tests in two checkouts do not use the same port.
- All checkouts on the computer share one test slot for each CPU core. Four checkouts on 10 cores run 10 test files at once, not 24.
- Seats in a game (part 10) run inside a macOS sandbox profile. A seat cannot read the games, the relay's state, or the folders and transcripts of other seats.
Code checkouts.js · stub-env.js · seat-boundary.js
Tests checkouts · stub-env · test-slots
05
Autopilot starts, reviews and merges work
Autopilot is the part of the relay that moves an approved ticket to merged code. Nobody has to press a button.
- Every 20 seconds, Autopilot starts the next approved ticket in Board order, one at a time. At most 3 tasks build at once, and the room has 9 desks. When main is red, Autopilot starts nothing.
- The first review starts after the checks on the pull request pass. The reviewer marks each finding as blocking, fix now or follow-up, and posts a verdict. The Dev fixes the code and pushes. Then a new review reads only the new commits.
- Autopilot merges with
--match-head-commit. It merges only if the last verdict says merge for that exact commit, and every check passed.
- In two cases, Autopilot gives the task to a person and says why. The first is 2 review rounds that still ask for fixes. The second is a change to the room's own rules.
Code autopilot.js · autopilot-plan.js · merge-hold.js
Tests autopilot · autopilot-stuck · merge-hold
06
The relay updates itself, and can roll back
If a change breaks the relay, no session can continue. That includes the sessions that could fix it.
- After Autopilot merges, the relay pulls main into its own folder. When no session is busy, it restarts on the new code. This is the loop that lets the room build itself.
- With the rollback switch on, an update applies new merges one at a time, oldest first. After each restart, the relay has 60 seconds to answer, serve the room page and take its sessions back.
- If the relay fails that check, the supervisor checks out the last commit that passed and starts the relay there. If that commit fails too, it does not roll back again. It never rolls back over changes that are not committed.
- The relay and the session host each give the version of the messages that they use. The relay never sends the session host a message that the host does not know.
Code update-steps.js · rollback.js · host-link.js
Tests update-steps · rollback · host-version
07
The Lead's context and memory
The Lead runs for a long time. Its context fills, Claude Code compacts it, and the Lead can forget a decision.
- The status line of each session shows how full its context window is. The Lead is fresh below 50%, getting tired from 50% to 69%, and needs a refresh from 70%.
- To refresh the Lead, the relay has it write handoff notes. Then the Lead gets a new, small conversation and reads the notes again.
- The relay types the Lead's brief again after
/clear and after compaction.
- The PM keeps one notes file for each repo, with at most 40 dated lines. A note is context, not permission. If a line reads like a permission, the PM checks it with you.
Code lead-tired.js · status-line.js · lead-refresh.js · pm-notes.js
Tests lead-tired
08
Tokens and rungs limit each session
Sessions run with your logins. So the limits on a session must be in code, outside the prompt, where that is possible.
- Each session gets its own token. A Dev's token can list and file tickets, post to the chat board, and report its own hooks and context. All other routes refuse it.
- The Lead's extra powers are rungs: move the Board, start tickets, stop sessions and merge. Each rung is off until the person turns it on. The rung to start tickets gives a number of starts, and it stops when none are left.
- Routes that can run commands answer only the room page on the same computer, and only with the key. A request through a tunnel or from another site gets 403.
- The relay removes its key from the environment of each session. The manual marks each guard as code or as brief only, so the gaps are written down.
Manual What a token reaches · Guards at each boundary
Tests lead-start · lint-ratchet