What you need to do
- Approve or reject Triage. What the PM and workers file waits there for you. Press Approve or Reject.
- Press Start. On a Ready card, when you want that work begun. Or let the Lead start Ready tickets, a few at a time (see The Lead starts tickets).
- Answer a worker who is waiting. Click them, then answer in the terminal. See how to tell, because a worker who asks a question in words does not raise a hand.
- Decide what a PR asks. Read what the worker wrote and what the reviewer posted. The relay tells the worker about new comments on its PR (see How findings get back to the Dev), so check that they act on what matters.
- Merge, then update the relay if needed. Workers are told not to merge. Merge on GitHub, or let the Lead merge a PR that is reviewed and green (see The merge rung). The room does not notice, and merged code is not live until someone pulls it. See Update, after a merge.
- Move the task along. In the Tasks panel, set the task to In review, Waiting on you or Done. Nothing else does, and this is what moves the card on the Board. The one other move is Needs you: a card shows in Waiting on you while that list names its ticket. The one exception: when the relay tells a worker about a review, it moves their task to Changes requested, unless the review's verdict says merge (see How findings get back to the Dev).
- Stop finished sessions. Click the worker, then Stop this session. Until you do, they keep their desk, unless you let the Lead stop them (see What the Lead stops). Marking a task Done does not stop its worker.
- Clean up. Once a task is Done and its worker stopped, Clean up on the task removes its copy of the repo. The branch stays. If the copy holds files git ignores, such as
.env, it names them and asks first (see A task).
How to tell what is waiting on you
When a session needs your OK for something, or is waiting on a question dialog, you get all of these:
- The tab title starts with a count, like
(2), and the top of the Floor says2 waiting on you. - They move to the top of the Floor list with an amber dot and the message.
- They raise a hand, stay in their chair and pass the time, and their name tag says
needs you. - The wall board gets a "needs you" note, and the Org chart has a Go to button for the first person waiting.
A question in words raises no hand. If a worker ends their turn with a question, the room sees a finished turn, and the Floor says Ready for a prompt. So read what the "ready" ones wrote. The Board's Waiting on you column helps only in part: it holds a Dev that stopped with no PR, but not one that stopped after it opened a PR.
| What you see | What it means |
|---|---|
| At their desk, typing | The session is working, unless the manager is visiting. See the manager. The Floor list is not fooled by the manager, but see the times below when it can be off. |
| Hand up, in the chair | Needs your OK, or has asked you something in a question dialog. Both say Needs your OK, so click them to see which. |
Floor says Ready for a prompt | Their turn ended and the session is still open. They may be finished, or they may have asked you something. They hold a desk. |
Floor says free | No session. The desk is open. |
| Coffee, couch, window, bar table, ping pong | Quiet. That is all it says. |
A worker playing ping pong is not working and is not asking you for anything. But the session may still hold a desk: check the Floor. Ready for a prompt means there is a session to read and perhaps stop, and free means there is nothing to do. The same goes for coffee and the couch. Any two quiet people but the Lead can start a game, and there is no game if your computer is set to reduce motion.
Times when the picture is off. Work with no new activity for 15 minutes ends by itself, in case an end was missed, so a very long command can look finished. Pressing Esc to interrupt sends the room no word, so the worker looks busy until your next prompt or those 15 minutes. Events sent while the page is closed are dropped. When you reopen it, sessions started here come back in the state the relay last heard, and ones from another terminal wait for their next event. Finish all also makes a working session say Ready for a prompt until its next tool call.
Needs you
The Floor and Autopilot each say what waits on you, in their own way, and they do not always agree. Needs you is one list for you, at the top of the Floor, under the Huddle bar. Its heading has a count, and under it is one line for each thing you need to do, most urgent first. When nothing needs you, it says Nothing needs you now.
Click a line to open what it names: the session at its desk, the PR or the failed CI run on GitHub, or the ticket on the Board. A line about another relay has a Stop button instead. A line about a session that also has a PR has a PR link after it. The page reads the list every 2 seconds.
Each kind of line has one rule. The list comes in this order:
- Stop another relay. Another relay uses this room's state folder, so it can erase what this relay saves (see Old relays). The line says
Stop the other relay, pid 48435: it runs ~/repo/Building58/relay/server.js on port 8790 since 2026-11-12 14:16 UTC.and why, and says when it is paused or has only its supervisor left. Its Stop button stops that relay and its session host, which ends the sessions in that host. The relay checks withpsagain first that the pid is still a relay on this folder. - Approve a permission. A session waits on you, and its message asks for permission. The line says
Approve or deny the request from Ada: Claude needs your permission to use Bash. It opens the session. - Answer a question. A session waits on you for anything else, or a menu or the trust question is on its screen. The line says
Answer Ada:and its message, orAnswer the question on the screen of Ada.It opens the session. - Free a desk for a review. Reviews wait for a desk, every desk is taken, and the relay may stop none of the sessions (A review frees a desk). The line says
Stop a session to free a desk: the reviews of PR #12 and #9 wait for one. All 9 desks are taken, and the relay may stop none of them.and which sessions the relay stops. It opens nothing, and has a PR link to the review that waited longest. It is not on the Board. It goes once a desk is free. - Look at a red main. The latest CI run that a push to main started failed (A red main). The line says
Look at the failed CI run on main of Building58: CI at 1a2b3c4 ended in failure. Autopilot starts no new ticket on main there until a push run on main passes.and the run's link. It opens the run on GitHub. It clears once a push run on main passes. - Fix what stops a GitHub write. With the GitHub ticket store, the last write to a ticket's issue failed, and the relay waits before it tries again (see When a write to GitHub fails). The line says
Fix what stops a GitHub write: the relay could not close issue #68. GitHub says:and GitHub's message, then when the next try is. The ticket's card shows the same line. It opens the ticket on the Board, and does not move its card. It goes when a write to the issue goes through, when GitHub already shows what the write wanted, such as an issue you closed by hand, or at the relay's first read of the issue after the wait. - Merge a PR that only you may merge. The task's PR is open, and the PR watch says it waits on you to merge it, because it changes a file only you merge or the Lead may not merge it. A line in the last huddle report that says an approved, green PR is ready for you to merge counts too. The line says
Merge PR #12 (T-5) yourself:and the reason. It opens the PR. - Decide on a PR Autopilot handed over. Autopilot handed the task's PR to you, and you have not moved its card since. This holds also when the relay moved the card out of Waiting on you for a new review comment. It ends when Autopilot takes the task back for a newer commit's merge review (Autopilot). The line says
Decide on PR #12 (T-5):and Autopilot's reason. It opens the PR. When the reason is that its Dev says a finding the review marked non-blocking is a bug, the line also has a Fix it button, which says you agree (see How you lift the push hold). When Autopilot handed it over because nothing moved it, and a review of the PR is posted with its verdict after that, the line says the next step that verdict gives instead, with a link to the review, since Autopilot's reason is old by then. Other hand-over reasons, such as a Dev saying a finding is a bug, stay, since a review does not answer them. This matters most while Autopilot is off, because then nothing takes the task back. A fix verdict saysBring back the worker on T-5 to fix PR #12: the review of 0fdd14b says fix, and its session has ended.and opens the ticket on the Board, or, while its Dev runs,Move T-5 out of Waiting on you: the review of 0fdd14b on PR #12 says fix, and its Dev Ada is running to fix it.A merge verdict saysMerge PR #12 (T-5), or move its card: the review of 0fdd14b says merge.and opens the PR. If the PR has newer commits than the reviewed one, it saysGet a review of PR #12 (T-5): the review of 0fdd14b says merge, but newer commits came after it., orsays fix, and opens the PR. - Get a review that could not start. The task's PR is open, its automatic review, first or follow-up, could not start 3 times, and no review of it runs (see Automatic review). The line says
Get a review of PR #12 (T-5): its automatic review could not start, and the relay stopped trying.and the reason, such as the file of a broken ref. It opens the Dev's session, where Get a review is, else the PR. - Look at a task in Waiting on you. Any other task in Waiting on you, with the note that put it there. It is left out while a review of its PR runs, while its PR's pipeline is running or failed, or while its Dev is at work, since the next move is not yours yet. It opens the PR, else the Dev's session, else the ticket.
- Open a session that did not start. The relay told a session something, and no turn began after it (see A session that does not start). It opens the session.
- Open a session a message cannot reach. A saved message for a running session has waited more than 15 minutes (
RELAY_UNDELIVERED_MS), and that session has no other line. It is left out while the session is in a turn or waits on you, since then the wait is not the problem. The line saysOpen the session of Ada: a message from the relay has waited 40 minutes for it and is not typed in, because its screen shows no prompt.The reason is the one the relay has for not typing: for example a menu is open on its screen, someone has text in its prompt, no hook reaches the relay from it, or its first brief has not gone in yet. It opens the session. This line is never on the Board, since it is about a session, not a ticket. - Prompt a Dev that stopped with no PR. A Dev is idle, and its task is in Building or Changes requested with no PR. The line says
Prompt Ada: it stopped on T-5 with no PR.A Dev that has not begun a turn a minute after it started saysPrompt Ada: it has not started on T-5.instead. A Dev that the relay will type a continue prompt into after a restart is left out until that prompt has gone in and its turn has ended. It opens the session. - Bring back a worker. A task in Building or Changes requested has no PR, and its session has ended. The line says
Bring back the worker on T-5, or move its card: its session ended with no PR.It opens the ticket on the Board.
Nothing shows twice for one cause. A session gives at most one line, and so does a task. A task whose Dev already has a line gives none, since answering the Dev is the one move.
The list reads only what the relay already keeps, so it asks gh and git nothing. A red main comes from the last answer the check of main kept. A merge line needs the PR watch to be on, or a huddle report, since only they ask GitHub who may merge. The huddle headline counts this list, and the Board's Waiting on you column holds the tickets it names (see The life of a ticket), so all three agree. A line for a session with no ticket, such as the Lead's, is not on the Board. The relay's side is relay/needs-you.js, with the rules in relay/needs-you-plan.js, and the page's is office/needs-you.js. See GET /needs-you.
The life of a ticket
A ticket is work that exists before anyone starts on it. These are the Board's columns, in order. How the room works draws the same life with every part that takes a step.
- Triageyou approve
- Readyyou press Start, or the Lead if you let it
- Buildingyou, in Tasks
- In reviewyou, in Tasks
- Changes requestedyou, in Tasks, or a review
- Waiting on youwhat Needs you names
- Donethe end
Rejected is not a column. Triage and Ready tickets can go there, and it is a folded list under the Board, with Back to Triage on each. From Building on, the Tasks dropdown can set any state in any order, so In review and Waiting on you can be skipped.
| Column | What it means | What moves it on | Do you need to do anything? |
|---|---|---|---|
| Triage | The PM or a worker filed it, and no person has looked yet. | You, with Approve, Reject or Merged elsewhere. | Yes. It waits for you for as long as it takes. |
| Ready | Approved, or filed by you with Add ticket, which skips Triage. No worker yet. | You, with Start, Reject or Merged elsewhere. Or a Lead you let start tickets. | Yes, when you want it built. Start stays off while the ticket is waiting for another; its card names which. |
| Building | It has a task, a copy of the repo, a branch and a worker. It stays here after the worker opens a PR, though the PR's link appears on the card. | You, with the dropdown in Tasks. | Answer the worker if they need you. Move it on when the PR is up. |
| In review | Whatever you decide it means: usually that the PR is up. It gets here if you put it here, or if you set it to Waiting on you and a review of its PR runs. Its card stays in Building while its pipeline is running or failed (see A clean pipeline before review). | You, with the dropdown. | Read the PR and the review. It also stops counting against the 3 being built. |
| Changes requested | The work went back for fixes: you set it there, or the relay did when it told the worker about a review (see How findings get back to the Dev). It has its own column so it does not look like new work. | You, with the dropdown. | Check the worker is on the fixes, then move it on when they are pushed. |
| Waiting on you | The started tickets that Needs you names, whatever their task's state: a task you set to Waiting on you, a Dev that waits on your answer, a PR only you may merge, a PR whose automatic review could not start, a Dev that stopped with no PR, or a worker whose session ended with no PR. A card whose task you set to Waiting on you, but that Needs you leaves out, shows where its work is: In review while a review of its PR runs, else Building, as while its Dev is at work or its pipeline is running or failed. | You, with the dropdown, or by doing what its Needs you line says. | Yes. Do what its Needs you line says. |
| Done | You marked the task Done, which frees any ticket that was waiting for this one. Merging does not do this. Or the ticket never had a task: its work merged outside the room, and you gave the PR that merged it with Merged elsewhere. That card links the PR and says "merged outside the room". From you, the relay takes any link of the form https://github.com/owner/repo/pull/12, and does not check on GitHub that it merged or that it is in the ticket's repo. From the Lead, it does check (see Work that merged outside the room). The column shows the latest 8, and Show N older under it shows the rest. | Nothing. Setting the task back to another state reopens the ticket, until Clean up removes the task. A ticket done with Merged elsewhere stays done. | Stop the worker, then press Clean up on the task. A ticket done with Merged elsewhere has no task, so there is nothing to do. |
| Rejected | You turned it down. Anything waiting for it stops waiting, and the card says it was rejected. A worker or the PM filing the same title from the same branch gets this ticket back, not a new one, though from another branch it makes a new ticket. You can file it again. | You, with Back to Triage. | No. |
The Board in its own tab. Open in its own tab, at the top of the Board, opens office/board.html with the room's channel and key, so you can keep the whole Board beside the room. It works only on this computer, like the room page. It does everything the Board on the room page does, from the same code (office/tickets.js), and adds:
- The columns fill the tab, and each scrolls on its own. Each column's heading counts its cards.
- A line at the top lists what is in Waiting on you and each ticket with a proposal for you, and the tab's title starts with how many, such as (3) Board. Click a ticket in the line to go to its card.
- A filter by text (in a ticket's id, title or details), by repo, by priority and by label, where No label keeps the tickets with none. Headings then say how many of each column match, such as Ready (4 of 9).
- The form to add a ticket or ask the PM is folded under Add a ticket, or ask the PM. The PM's name shows once the relay has seated them.
Cards in both places name the ticket's priority, task state and who has it (see its history). Anyone else the relay has seated on the ticket shows as also with, from the Floor. In the tab, a running session in a card's history says to open it from the room page, since the tab has no terminal. The line above the columns gives the WIP limit, which counts Changes requested as well as Building, as the limit explains. The room page does not ask for the Board. The relay sends it on the event stream the page already holds, once when the stream opens and again only when something a card shows has changed: it looks once a second, and at once after a change made on the Board or with ticket.js. The time a pipeline was last checked is not on a card, so a new check with the same result sends nothing. While that stream is down, the room page asks with GET /tickets every 10 seconds until it is back. The tab asks the relay every 2 seconds and keeps no connection open, so the room page and its terminal keep theirs. On both Boards, a change redraws only the cards whose content changed, matched by ticket id. Every other card, and each column, stays as it was, so where each column and the Board sideways were scrolled stays too. While a picker or text box on a card has focus, the Board does not redraw. It catches up as soon as you leave the control. If the address has no channel or key, the key is wrong, or the relay stops answering, the tab says so at the top, and keeps the last cards it had.
The order of the cards. Each card shows its priority: high, normal or low. Within a column, the cards go high first, then normal, then low, and in work order within a priority. Done shows the latest first, and so does the Rejected list. The relay works the order out each time the Board asks for the tickets, so closing a ticket changes no other ticket. A ticket saved with no priority counts as normal. node relay/ticket.js list prints the tickets in the same order: the open ones first, then the done and rejected ones, the latest first, each line with its status and priority, and (set by the person) at the end when you set its priority or place last.
Reading one ticket. node relay/ticket.js list gives one line per ticket, with no body. node relay/ticket.js show T-5 prints one ticket in full: its id and title, then its status, its priority and who filed it (the person; the session's name and (a session); with the GitHub store, an issue someone opened on GitHub shows their login and on GitHub, such as alice on GitHub; or not recorded when the store kept no filer), then the tickets it is blocked by, each with its status and title, or nothing, and last its body, or (no body). It reads the same list as ticket.js list, so any session that can list tickets can show one, and it changes nothing. The id may be in any case, such as t-5. An id that is not on the Board gets an error that says so and exits with 1.
Folded cards. Done always shows its cards in one closed group, Latest, with its count. Show older is inside it. When Triage or Ready holds 7 cards or more, its cards fold into one group per priority: High, Normal and Low, each with its count, and only the priorities it has. Pick Fold by label, above the columns on the room page and in the Board's own tab, to fold them into one group per label instead, A to Z, then No label. A ticket with two labels is in both groups, so the counts can add up to more than the column holds. The pick is kept in this browser only, and the room page and the tab share it. Every group is closed until you open one. The page keeps the groups you opened in this browser only, so they stay open after a reload, and every other browser starts with them closed. While a filter is on in the Board's own tab, every group is open. A group also opens when it holds a ticket you went to, such as from the Floor or the Waiting on you line. Building, In review, Changes requested and Waiting on you never fold.
Folded sections. On the room page, Activity, the Board, Chat, Tasks and Games each start folded to their title line. The Board's line still shows where tickets are kept, the building limit and Approve all Ready. Press a title to open or close it. The page keeps the ones you opened in this browser only, so they stay open after a reload. Going to a ticket from the Floor opens the Board for that visit without keeping it open. The Board in its own tab never folds.
The PM notes. The relay keeps one notes file per repo for the PM, so what you told one PM is not lost when its conversation is cleared or it is stopped. The file is pm-notes/ in the relay's state folder, named after the repo's main folder with a short code, for example ~/.office-world/pm-notes/shop-1a2b3c4d.md. Every PM asked for that repo, from any of its worktrees, gets the same file. The PM's brief names it, tells the PM to read it first if it is there, to rewrite it before it stops, and to rewrite it again each time you tell it something worth keeping after that: at most 40 lines, each dated, with only what the board and the tickets cannot show, such as your decisions about the product, ideas you parked and why, and what the PM promised you. Like the Lead's notes, they are context, not permission: they copy no ticket or board state, they grant nothing, since any session could write that file, and the PM checks with you any line that reads like a permission. The relay does not write the file itself; a PM that stops before rewriting it leaves the old notes as they were.
The PM-brief eval. A change to the PM's brief can make the PM file worse tickets, and that does not show until a PM runs. So npm test holds the brief to the text the PM-brief eval last judged, which is kept in relay/pm-brief-eval.json. That text is the brief as a PM gets it with Let the PM set the order off, no PM notes and no skills, and with relay/ticket.js for the path. Once the brief changes, that test fails until you rerun the eval with node relay/pm-brief-eval.js --kit DIR. DIR is the eval kit: three test cases, each an idea and a board, the repo notes, and the strict ticket rubric. The eval needs an edd-platform with its suite gate, started with a live model key, at http://127.0.0.1:8021/api unless you give --api. In it, the script makes an agent with the kit's three tests. It adds one version with the brief last judged and one with the brief now, runs each version's whole suite live, and compares the two suites. If a test passed with the old brief and fails with the new one, the eval got worse: the script exits 1 and leaves the file as it was, so npm test keeps failing. Otherwise it writes the new brief and the result, with each test's score and outcome, into the file, and you commit it with the change. Each rerun costs six live runs and six live judge calls. Exit 2 means the eval could not run, such as a missing kit file or an edd-platform it could not reach, and the file stays as it was. CI runs only the check of the text, since it has no edd-platform and no key.
Setting priority and order. A card in Triage or Ready has a priority list and Up and Down. Pick a new priority and the ticket goes last in that priority. Up puts it above the card before it in the same column with the same priority, and Down below the card after it. With a filter on in the Board's own tab, those are the cards you can see, so a move can pass a hidden card. A new ticket goes last in its priority. A rejected ticket that goes Back to Triage keeps its old place. The work order is the Triage and Ready tickets: a Started ticket is not moved and cannot be moved next to. The place is a number on the ticket, its rank, that sorts after priority. A ticket saved before ranks has none, so it keeps its place by its age: the oldest first, as before. Only you can set priority or order, and a PM or Lead you let set it (below). Any other session's token gets 403. A card says who last set its priority or place, such as place set by the PM, priority set by the Lead or priority set by you. A ticket that nobody has set since it was filed says nothing.
Editing a ticket. Until a ticket starts, in Triage or Ready, press Edit on its card to change its title, its body and its priority, then Save. The limits are those of filing one: a title of 1 to 80 characters and a body of up to 8000. Only the fields you changed are sent. A title that another open ticket in the repo has on the same branch is refused, so pick another or use that ticket. For the PM and the Lead, a title you rejected is refused too, so they cannot bring it back by renaming. If someone else changes a field while your form is open, Save leaves it as they set it, unless you changed that field too. A new priority puts the ticket last in that priority, as the card's priority list does. Once a ticket is starting or has started, is done or is rejected, it cannot be edited. The PM and the Lead can edit too, with node relay/ticket.js edit T-5 --title "New title" --body - <<'EOF' (see ticket.js). Neither needs a switch for the title and body, but a new priority needs Let the PM set the order or Let the Lead set priority, and without it the relay refuses the whole edit. When the PM or the Lead changes the title or body of a Ready ticket you approved, your approval goes, since you approved other words: the card says it is not approved by you, and Approve all Ready offers it again. Your own edits keep your approval. No worker or reviewer can edit a ticket. Each edit is a step in the ticket's history, with who made it, when, and which fields changed.
Proposals to replace, merge or close a ticket, or to change its blockers. The PM cannot reject a ticket, and neither the PM nor the Lead can change a ticket's blockers, but both can propose it, and you decide. Four kinds, each for a ticket in Triage or Ready: replace names the tickets that take its place, merge names the one ticket that has the same work, close names none, and blockers gives the whole new list of tickets it waits for, which can be empty. Each can carry a reason of up to 500 characters. The card shows the proposal in one line, such as The PM proposes to replace T-10 with T-18, T-19. Why: Split into two., with Approve proposal and Decline proposal, and in the Board's own tab the ticket is in the waiting line at the top. Nothing changes until you press one. While a proposal waits, the ticket is held back, so Autopilot and the Lead do not start it. When you approve a replace, merge or close, the ticket moves to Rejected, and the Rejected list says replaced by T-18, T-19, merged into T-8 or closed. Its chat channel is archived, as for any rejected ticket. When you approve blockers, the ticket waits for the new list. The relay checks the proposal again when you approve it: a ticket it names that is gone or rejected, a ticket that waits for this one and so cannot block it, or a ticket that has started is refused, and the proposal stays for you to decline. A new proposal on a ticket takes the place of the old one. If the ticket is rejected, marked done or started some other way, its proposal goes. Its history shows the move, or for a start, that the proposal was dropped when the ticket started. The PM and the Lead run node relay/ticket.js replace T-10 --by T-18,T-19 --why 'Split into two', merge T-24 --into T-8, close T-5 or blockers T-19 --blocked-by T-18 (see ticket.js). No worker or reviewer can propose. Each proposal, and your answer, is a step in the ticket's history.
The PM sets the order. With Let the PM set the order on, in Settings under COO and PM, the PM can set the priority and place of a ticket in Triage or Ready with node relay/ticket.js priority T-5 high and node relay/ticket.js order T-5 --before T-4 (or --after T-4), the same rules as your picker and Up and Down. It is off by default. The relay keeps it in the settings file, so it stays off after a restart until you turn it on, and it stays on until you turn it off. The PM's token gets 403 while it is off, for a ticket that is started, done or rejected, and for any move, start or change of base, whether the switch is on or off. If more than one PM is running on the channel, only the one that started last can set the order. The relay's log says each change the PM made. You can still set any ticket's priority or place, and the card then says it was you. Its brief tells it to give each ticket it files a priority, and to order work by the goal in the constitution: stronger checks first, then fewer decisions for you, then a truer room, then looks. With the switch on, the brief tells it to run ticket.js list, place its new tickets among the Triage and Ready tickets of the same priority, reorder Triage and Ready tickets, leave alone any ticket whose priority or place you set last on the Board (the list marks it (set by the person); a ticket you filed with a priority is not marked, and the mark goes once the PM or Lead sets that ticket, so it is not a lock), and end with one short list of what it changed and why. With the switch off, the brief tells it not to run priority or order, and to recommend an order in its reply instead. The relay reads the switch when you press Ask the PM, so a PM asked while it was off still has the brief that says off. Ask a new PM after you turn it on.
The Lead sets priority. With Let the Lead set priority on, in Settings under The Lead, the Lead can set the priority and place of a ticket in Triage or Ready with the same two commands as the PM, node relay/ticket.js priority T-5 high and node relay/ticket.js order T-5 --before T-4. It is apart from Let the Lead move the board: it does not need it, and it does not let the Lead move, start or change the base of a ticket. It is off by default. The relay keeps it in the settings file, so it stays off after a restart until you turn it on, and it stays on until you turn it off. Like Let the Lead stop sessions, it stays on when you make a different session the Lead, and then only the new Lead can use it. The Lead's token gets 403 while it is off and for a ticket that is started, done or rejected. The relay's log says each change the Lead made, and the card says set by the Lead. You can still set any ticket's priority or place, and the card then says it was you. While it is on, the Lead's brief says it may order Triage or Ready tickets with those two commands when you ask, and must never undo a ticket you set, which ticket.js list marks set by the person. While it is off, the brief says nothing of it. Turning it on or off types the brief to the Lead again. Only the brief stops the Lead from setting a ticket you set: the relay does not check it.
The Lead starts a review. With Let the Lead start reviews on, in Settings under The Lead, the Lead can ask the relay for a review of a task's PR with node relay/ticket.js review https://github.com/owner/repo/pull/12. The relay starts the reviewer that Get a review starts on a session with a PR: the same brief, in its own checkout of the PR's latest commit. It takes a desk, shows on the Floor, posts its findings on the PR without asking, and leaves. The PR's Dev is told the review started, as for every review. The relay refuses a PR that is not a task's PR, a PR that a reviewer is already reviewing, an ask when no desk is free, and a PR that has had Automatic reviews per PR (3): the Lead's reviews count with the automatic ones, so the loop stops at the same limit, and the next review is yours. A review the Lead asks for takes the place of a first review that waits for the pipeline, or a follow-up that waits, so the PR does not get two. The Lead's brief says to start reviews this way and never to review in its own session, itself or with a subagent, since the Floor cannot see that. The switch is off by default. While Autopilot is on, the Lead may start reviews as if the switch were on, and Settings says on while Autopilot runs beside it. When Autopilot is off, the switch decides again. The relay keeps it in the settings file, so it stays off after a restart until you turn it on. It stays on when you make a different session the Lead, and then only the new Lead can use it. It does not need Let the Lead move the board, and it does not let the Lead move, start or merge anything. The task's history says the Lead asked for the review, and the ticket's history says the Lead started the reviewer.
Work that merged outside the room. If someone delivered a Triage or Ready ticket's work in a PR the room did not start, press Merged elsewhere on its card, paste the PR link, and press Mark done. The ticket goes to Done with that PR, nobody can start it again, and anything waiting for it is freed. Only you can do this, or a Lead you have let move the board. The relay refuses a PR that already belongs to another task or another ticket, and names it, so one PR cannot close two tickets. When you press Clean up on a task, its ticket keeps every PR the task gave, so those PRs stay refused after the task is gone. If the ticket store cannot keep them, such as a GitHub issue whose note another key signed, Clean up still finishes, and the relay's log says those PRs will not be refused. When the Lead does it, the relay also asks gh pr view about the PR first, and refuses it unless it merged and its repo is one of the GitHub remotes of the ticket's repo, since a Lead can paste the wrong link. If the ticket changes while the Lead's move waits, from one that may not move to Done into one that may, such as from Rejected back to Triage, the relay refuses the move and the Lead moves it again, so no link skips that check. A remote counts by its fetch or push URL, after any insteadOf rewrite in your git config, and a repo renamed since counts under its old name too. A remote through an SSH host alias, such as git@github-work:owner/repo.git, does not count, so mark that ticket Done yourself. It refuses too when gh cannot read the PR. The relay's log line says which PR the Lead gave. Check the link first: Done cannot be undone from the Board.
A ticket that has started cannot be rejected. The only way to end it is to stop the worker and set its task to Done, and that records it as finished, as if the work had been completed. Anything waiting on it is freed and can start, so check those first. Setting the task back reopens it, until Clean up.
Tasks without tickets. New task in the Tasks panel starts work right away with no ticket, so it never shows on the Board. It does show on the board on the brick wall, which lists tasks, not tickets. The wall board also shows a "needs you" note for anyone with a hand up. When there are no tasks at all it shows what each person is doing instead.
Filing. You file with Add ticket. Ask the PM uses the same boxes for your idea. Filing the same title twice from the same branch gives you the first ticket back, and what you typed stays in the form. Only a worker or the PM can make a ticket wait for another, with --blocked-by. The relay refuses a blocker id that no ticket has. A ticket the PM files needs a body with the parts What to build, Acceptance criteria, Blocked by and Out of scope, each at the start of its own line. The relay refuses one without them and names the missing parts. Your tickets and other sessions' tickets can have any body, since a short follow-up does not need four parts. Workers and the PM can have at most 20 tickets in Triage. Which branch a ticket starts from is in Copies of the repo, and branches.
Likely duplicates. Two sessions sometimes file the same work under different titles. So when a ticket is filed, the relay compares it with the open tickets of the same repo, those in Triage, Ready or Started (relay/ticket-twins.js). It takes the words of each title, and the words of each title and body together, and leaves out small common words such as the, to and fix. Two tickets look like the same work when they share at least 2 words and those shared words are at least 40% of all the words in the two, for the titles or for the titles and bodies. For example, Fix the hang in tickets.test.js and tickets.test.js hangs on the github store share hang and tickets.test.js, 2 of their 4 words, so they match. The relay names up to 3, the closest first. This is only a warning: the ticket is filed all the same. ticket.js create prints the likely duplicates under Filed, and says that one of the two should be rejected: the Lead rejects it with ticket.js move, and any other session tells @Lead. When you file with Add ticket, the note under the form names them, and you reject one if it is the same work.
Kind. A ticket can have a kind, which says what sort of work it is: docs, tests, bug, feature, or one you added. A worker or the PM sets it when they file, with --kind, and may use only a kind there is already; ticket.js kinds lists them. You add a kind by giving it to a ticket. A kind is one short word: a lowercase letter, then letters, digits or dashes, up to 24 in all. A ticket filed with Add ticket or without --kind has no kind, and its card says no kind. Until it starts, in Triage or Ready, press Change kind on its card, type a kind or pick one, and press Save (POST /tickets/{id}/kind). An empty box takes the kind away. Only you can change it, and once the ticket starts its kind stays. The COO counts each run under its ticket's kind. Nothing else acts on the kind yet.
Labels. Labels sort a long Board. A ticket can have up to 5, each one short word in the same form as a kind, such as flaky or follow-up. Nothing in the room acts on them: they only fold and filter the Board. Press Labels on a card, type the labels with commas between, and press Save (POST /tickets/{id}/labels). What you save replaces the labels the ticket had, and an empty box takes them all away. The box names the labels in use. You can change labels at any status, since no measure counts them. A card says its labels after its kind. A label is in use while a ticket has it, and the Board offers only those. You add a new one by giving it to a ticket. A worker or the PM can give labels already in use when they file, with --label flaky,follow-up, but cannot add a new one or change a ticket's labels; ticket.js labels lists them. With the GitHub store, labels are kept in the issue's hidden note, not as GitHub labels.
On hold, replaced, and design tickets. Sometimes a Ready ticket should not start yet: you paused it, a newer ticket took its place, or a design ticket is still deciding its shape. You mark it so, and Autopilot and the Lead start none of these until the mark is cleared or the design ticket is done or rejected. You can still press Start yourself. The card says why, such as On hold. Nothing starts it by itself until you clear the mark. or Waiting on design ticket T-15, which shapes it. The rule is heldBack in relay/autopilot-plan.js.
- Hold on a card in Triage or Ready puts it on hold. Take off hold clears it.
- Replaced asks for the ticket that replaces it, which you can leave empty, and Mark replaced saves it. Not replaced clears it. Both go through
POST /tickets/{id}/mark, and only you can set or clear a mark. - Shapes on a card in Triage, Ready or Started makes it a design ticket: type the ids of the tickets it shapes, with commas between, and press Save (
POST /tickets/{id}/shapes). The card then says shapes T-7, T-9. While it is in Triage, Ready or Started, those tickets wait. An empty box takes the list away. A ticket that is Done or Rejected keeps the list it had: the relay answers409not_readyto a change. A worker or the PM can name them when they file a design ticket, with--shapes T-7,T-9, but only tickets still in Triage, so a session cannot make a ticket you already approved wait. The relay checks this only when the design ticket is filed. If you approve a named ticket later, it still waits for the design ticket, as its card says. The relay refuses the whole filing if one named ticket has left Triage, unless the filing has the same title as a ticket that is not done: then the session gets that ticket back, as for any filing of the same title. They cannot change the list after.
How assignment really works
- Only a start assigns. Pressing Start, or a Lead you let start tickets running
ticket.js start, makes a copy of the repo, a new branch and a Claude Code session, then types the ticket in as the worker's brief. Nothing watches Ready and picks tickets up. - Which person gets it is only a free desk. The relay picks the person each of its sessions is (
relay/seats.js), and every page, tab and the Floor show the same. Each session takes the first free desk in the roster, and keeps it until it ends, through page reloads and relay restarts: the relay saves each session's desk and name with its sessions./clearand/resumekeep the person, since the terminal stays the same. The Lead's desk belongs to the session you made the Lead. When you make one the Lead, it moves to the Lead's desk at once, and whoever sat there moves to a free desk. Anyone else sits at the Lead's desk only when every other desk is full, so the person called Paul may not be the Lead then: the Floor saysThe Leadbeside the real one. Such a session moves to another desk as soon as one is free. While the relay brings sessions back after a restart, a new session passes over the people they had. A desk is a look, and the name is drawn apart. The roster has a pool of 50 names, 25 for desks that look like a woman and 25 for desks that look like a man (each desk'skind). Each session the relay seats takes the least recently used name of its desk's kind that no running session has, and keeps it until it ends, through/clear,/resume, page reloads and relay restarts. Bring back on a task starts its session again at a free desk, with the name that comes next. Names never used come first. A name comes back only once the others of its kind have been used, so a full day shows many names. Each room keeps its own record of when it last gave or gave up each name,names.jsonin its state folder, and goes through names never used in its own order, which comes from its state folder. So two rooms, each with its own state folder, are unlikely to show the same name at once. The Lead at the Lead's desk is called by that desk's name, Paul, after Paul in Building 58. The role is still called the Lead. A name in the pool is one word of letters. A desk's own name, which a session shows at the Lead's desk as the Lead, when its kind has no pool, or when every name of its kind is taken, keeps at most 40 characters and loses control characters, zero-width characters and bidi controls, so no name can hide or reorder text where it prints, such as the Lead's terminal. A session that moves to a desk of the other kind, such as the Lead leaving the Lead's desk, takes a new name. The desk's own name, such as Priya, shows only while no session of the relay's sits there. The Floor,ticket.js stop, @mentions in chat, review messages and ticket history all use the name the session shows. The relay reads the roster from the filerosternames inoffice/world.json, when it starts, so restart it after you change who works here or the names. Sessions from your own terminal, which the relay does not run, are seated by the page: see Sessions from your own terminal. It is not a skill match. Priya's "Debugging" and Marcus's "Tests" have nothing to do with who gets which ticket: the roster's skills are used only by theworkaction (see the room's API). - There are nine desks, so nine sessions at a time. That counts every session started from this page: tasks, the PM, reviewers and Add worker.
- A finished session keeps its desk until you stop it, or the Lead does, if you let it. A worker who has opened a PR and a PM who has filed tickets still hold a desk. One exception is an automatic reviewer: about 30 seconds after it posts its review, it leaves by itself (see Reviewers leave once they have posted). So does one from Get a review on a session with a PR. One from Get a review on any other session stays. Another exception is sessions started from your own terminal: see Sessions from your own terminal.
- At most 3 tasks are being built at once, unless you change the WIP limit in Settings (or
RELAY_WIP_LIMIT). That counts tasks in Building or Changes requested with a running worker, except a task the relay moved to Changes requested from a column that does not count, such as In review. So a review arriving never makes Start or Bring back be refused. Only the relay's own move for a review leaves a task out like that. The task's next move, by you, the Lead or Autopilot, makes it count again, and a move of it to Building is refused at the limit like a start. A move throughPOST /tasks/{id}/movethat saysby: relayis a move like any other. A relay restart brings back every task that was building, even past the limit, since the limit stops new work and not work already running. Tasks can be over it after you lower it, or after Autopilot takes back a stuck task. Moving one to In review frees a place, and so does stopping its worker. The PM, reviewers and Add worker do not count. - Stopping is not losing. A stopped task's worker can return with Bring back on the task, in the same conversation and the same copy of the repo. That button does not show on a Done task, so set the task back to another state first, and not after Clean up.
Who has a ticket, and who worked on it
On the card. Each card on the Board says who has the ticket now, such as with Priya, Dev, or Unassigned. The Dev has it while its task is in Building or Changes requested. In review, the reviewer has it: one running now, or else the latest one. With no reviewer yet, the Dev still has it. While its task is in Waiting on you, you have it. Before it starts and once it is done, nobody has it. If that person's session has ended, the card says (session ended).
In the card's detail. Open a card to see each step, oldest first, with its time: who filed it, who approved it, who started it (you, the Lead or Autopilot), each Dev session, each reviewer with whether you or an automatic review started them, each move, with who made it, and each edit, with who made it and which fields changed: title, body or priority. A step by the Lead names the Lead's person too. Each step that was a session shows:
- its full session id, with Copy id, and the folder it ran in. Claude Code finds a session by its folder, so Resume needs both.
- Open its terminal while it is running, which shows it in the panel.
- once it has ended, how to bring it back: put the id in Resume with that folder. If the folder is gone, as after Clean up or when a reviewer's checkout went, it says it cannot come back.
After /clear or /resume, a Dev or a reviewer is a new session in the same terminal, so it gets a new step with its new id, and the step before it shows that session as ended. A reviewer started after its task's Clean up is still a step on the ticket: the relay finds the ticket from the PR, which the saved history keeps on each reviewer and on each move made once the task had its PR.
There is no web page for a session on this computer, so nothing here links to one. A session's conversation is saved by Claude Code on this computer, and the Board does not show it.
Where the names come from. The relay names each session it seats (see Which person gets it). It keeps each name against the session's id when it arrives, in RELAY_TICKET_HISTORY_FILE. So a reload, another tab and a relay restart show the same names, and a session that has ended keeps its name. A session the relay never named shows its role with no name recorded.
What is kept. The history is kept apart from the task, so it stays through a relay restart and through Clean up, which removes the task. A ticket from before histories were kept shows only what its ticket and task still say: who filed and approved it, who started it, the Dev's session and the task's moves. A step with no time recorded says time not recorded, and no names are guessed.
Who does what
| Who | What they do | What they cannot do |
|---|---|---|
| You | File, approve, reject and start tickets. Move tasks. Answer workers. Merge, and take back the Lead's right to merge with a PR. Stop and clean up. Give the Lead each of its permissions, and take them back. | Type into a session started from another terminal. You can only watch those. |
| The Lead | Watches open PRs and the board, passes decisions along, checks that Devs act on the reviews the relay gives them (see How findings get back to the Dev), keeps tickets moving, marks PRs ready to merge with a note and a label, tells you what is waiting on you, and checks claims against the code and the pipeline before calling work ready. With the permissions you give it, it also moves the board, merges under the merge rung, stops sessions, starts tickets and starts reviews of a task's PR. See The Lead. | Take ticket work: it is told not to. Clean up a task, or start sessions, except the worker for a ticket it starts and the reviewer of a task's PR it asks the relay for. Review code in its own session: it is told not to. Do any of the moves in The Lead that you have not let it do. Set a ticket's priority or place, unless you turned on Let the Lead set priority, and then only for tickets in Triage or Ready. |
| A Dev (task worker) | Builds in their own copy of the repo, on their own branch. Is told to push and open a PR against the ticket's base, with a title that starts with the ticket number and a colon, as in T-12: A help page on how work moves, and can list and file tickets. Is told to file a ticket with its body on stdin in a quoted heredoc. A task with no ticket, from New task, has no number, so its brief does not ask for one. Is told to run npm run lint before it pushes and do what its messages say, and never to change eslint.config.js, eslint-local.js or eslint-suppressions.json to pass it. Is told to keep CLAUDE.md and docs/constitution.md out of its PR, so Autopilot can merge the code (see CLAUDE.md and constitution updates). | Move the board or approve their own ticket. Is told not to merge. After a review that asks for fixes, it fixes each blocking and fix-now finding in the same PR. After a review whose verdict says merge, it does not push for it, and files a ticket only for a finding that is a real bug or risk outside the PR (see How findings get back to the Dev). Its checkout then refuses a push, except a merge of main, until a later review or you say fix (see The push hold). |
| A reviewer | Reads a PR and posts findings as a PR comment, then leaves by itself. With Get a review on a session with no PR, reports in their own terminal and stays. | Move the board. Is told to change nothing, commit nothing and merge nothing. |
| The PM | Started by Ask the PM. Is told to read the repo's CLAUDE.md and docs/constitution.md, each if there is one, then split your idea into tickets, which wait in Triage. Is told to write each ticket in four parts: What to build, Acceptance criteria that name the seams to test at, Blocked by, and Out of scope, describing behavior rather than file paths. The relay refuses a PM's ticket whose body lacks one of those parts at the start of a line, such as Blocked by: none or a ## Blocked by heading, and names the missing ones. Is told to file each body on stdin in a quoted heredoc (see ticket.js). Is told to file code tickets without changes to CLAUDE.md or docs/constitution.md, and to gather those changes into one ticket (see CLAUDE.md and constitution updates). Is told to give each ticket a priority, and to set or recommend an order (see The PM sets the order). Is told to read the PM notes for the repo first, to rewrite them before it stops, and to rewrite them again each time you tell it something worth keeping after that. Reads the branch of the folder you typed, the way a worker would start from it: the relay fetches, and the PM works in a checkout of its own at the remote's latest commit of that branch. So asked from a folder that is behind, the PM still reads the newest rules, and asked from a linked worktree, it reads that branch. Their tickets record that branch as their base. That includes a task's checkout under .worktrees, whose branch goes away when the task is cleaned up, so ask from the main folder or your own worktree. The branch is read once, when you ask, so if you switch that folder's branch while the PM runs, their tickets still record the branch it had. Asked from a subfolder, the PM reads the branch of the checkout that holds it, and starts at the top of its own checkout. A folder on no branch is refused. | Move the board or approve their tickets. Set a ticket's priority or place, unless you turned on Let the PM set the order, and then only for tickets in Triage or Ready. Is told not to change code, commit or open a PR. |
| The COO | Started by Ask the COO. Reads the room's measures and writes a one-page report on how the room runs and how close it is to running itself, with at most 3 recommendations. Has its card in the Officers row of the org chart. See The COO. | File tickets: the relay refuses them from its token. With its token, read anything but the measures and the tickets, or save anything but its report. Is told to propose only: to change no code, open no PR, and never start, stop or merge work, move the board or change a switch. |
| The security officer | Started by Ask security. Reads what access the room's sessions run with, by name only, and writes a one-page report against article 7, with at most 3 recommendations. Frames the risk and says when to escalate. Has its card in the Officers row of the org chart. See The security officer. | File tickets or read the chat board: the relay refuses them from its token. Save a report that holds a key. With its token, read anything but its measures and the tickets. Is told to propose only and not decide: to change no code or access, open no PR, and never start, stop or merge work or change a switch. |
"Is told" means the words in their brief. The brief is words, not a lock: it cannot stop a session doing something else if you ask it to.
CLAUDE.md and constitution updates. Only a person merges a PR that changes CLAUDE.md or docs/constitution.md, so Autopilot hands such a PR to you, code and all. To keep code from waiting on wording, these changes go to one open ticket titled CLAUDE.md and constitution updates, and code PRs leave both files out. A Dev whose change also needs one of them updated is told to write the exact change in its PR body and leave both files out of its PR. Once the PR is open, it runs ticket.js create "CLAUDE.md and constitution updates" with a body that names its ticket, the PR and the change. If none has that title, that files it. If one is in Triage or Ready, ticket.js says Already filed with (triage) or (ready), and a Dev cannot edit a ticket, so it posts in its own ticket's chat channel, starting with @Lead and naming that ticket and the PR, and the Lead can add the change with ticket.js edit. A task with no ticket has no chat channel, so its Dev says so in the PR instead. Already filed also answers for a ticket of that title that has started or that you rejected, which nobody can edit. Then the Dev files the change as its own ticket, titled CLAUDE.md and constitution updates for T-12 with its own ticket's number, blocked by the started one. The PM is told to file code tickets without changes to the two files, and to add each change to the open one, the ticket in Triage or Ready whose title starts with CLAUDE.md and constitution updates, with ticket.js edit, not one ticket per change. If none is open, it files one. If that title has started or you rejected it, the PM adds today's date to the title, and blocks the new ticket by a started one. Each change added to a ticket you approved takes your approval back, so the ticket waits for you again. Once you merge that ticket's PR, the next change starts a new one. Only a code change that cannot ship without the wording, because the constitution must describe what the code does, carries it in its own PR, which says why, and that PR then waits on you as before.
Skills and models. Each role's brief, the Lead's, a Dev's, a reviewer's, the PM's, the COO's and the security officer's, ends with one paragraph that names the skills set for that role in Settings, under Models and skills, such as mattpocock-skills:tdd. It tells the session to use them where they fit, to read the SKILL.md of a skill only a person can run and follow it, to carry on without one that cannot be called or read, and that the repo's rules win where a skill and CLAUDE.md or the constitution differ. It names only skills installed on this computer, and none when the list is empty. The PM's paragraph comes before its idea, so the idea is still last. A skill changes how a session does its job, not what the job is, so the rest of the brief, with its limits, is the same (the constitution, article 6). Each role can also have its own model, which a new session for that role starts on.
The Lead
Choosing it. The Lead is the session you choose with Make this the Lead, with it on screen. Only a plain session can be chosen, not a task, the PM or a reviewer, and sitting at the Lead's desk does not make anyone the Lead. There is one at a time, and a new one replaces the old. When the relay starts, it gives the room a Lead by itself (see When the relay starts).
Its brief. The relay types the Lead's brief as a prompt. It gets the brief again after /clear, after its conversation is compacted, and after Bring back, which spends a turn each time. It is a first brief: nothing else is typed into the Lead before it. The brief goes in only when the session's hooks say it is idle, or a new conversation has begun, and never because of silence or a timer, since typing at an open question would answer it. So after an interrupted turn, or Esc at a question, it waits until you send any prompt and that prompt finishes, or until you run /clear. A note under the room bar says so while it waits. With no hooks reaching the relay, a session you have spoken to is not briefed at all.
When the relay starts. The relay saves the Lead (RELAY_LEAD_FILE). When it starts, once it has taken back and brought back its sessions, it gives the room's channel (the channel in office/world.json) a running Lead by itself:
- If a Lead came back with the other sessions, it does nothing. There is never a second Lead.
- If the saved Lead is not running, it brings it back as Bring back would, with the permissions the file says you granted, and nothing more. A Lead you stopped before the relay stopped comes back too.
- If there is no saved Lead, or it cannot come back (the start is refused, or
claude --resumeends with an error within ten seconds), it starts a new plain session and makes it the Lead. It starts in the folder the relay runs in, which is the folder the panel shows first, and in that folder itself, not a checkout of it, since the Lead takes no ticket work. It gets the Lead's brief and the Lead's model, and every permission below is off.
The relay's log says which it did. It starts no Lead while an update is under way, or when every desk is taken. Since there is then a Lead, the panel offers nothing back. RELAY_LEAD=0 turns this off, and RELAY_RESUME=0 starts the relay with nobody, the Lead too (Settings). With RELAY_LEAD=0, the panel offers the saved Lead back after a restart, keeping the Lead's desk until you answer. Only Bring back makes it the Lead again. If you answer Not now, or put its id in Resume, it is a plain session until you choose it.
When the Lead's session ends. Stopping the Lead loses its turn in progress, and no session is the Lead until it comes back. Only its handoff notes carry over. So it is hard to stop by accident:
- Stop this session on the Lead asks first. It says what is lost and how to get it back, and offers Stop the Lead, Refresh the Lead instead and Keep it running. Other sessions still stop with one click.
- The relay refuses
POST /terminals/{id}/stopfor the Lead unless the request sayslead: true(routes). - The Lead's desk is never safe to stop, so neither the Floor's Stop all safe,
ticket.js stopnor Autopilot stops it. - Clean up, on a checkout or on a task, refuses a checkout that the Lead runs in, or that the saved Lead last ran in, and says to make another session the Lead first. A checkout like that is not removed by itself when its session ends either.
If the Lead's session ends anyway, because you confirmed the stop, it ended by itself or it crashed, the panel says so at once. The page notes and a line above the Floor say that no session is the Lead now and offer Bring back as the Lead, which resumes the same conversation as the Lead, with its permissions. ticket.js floor prints the same line. Not now takes the offer away until the next relay restart. The offer shows only while no session is the Lead, so once the relay or you make a new Lead, the old one is not offered. A Lead that never had a conversation is not saved, so it cannot come back: the panel says so, and you make another session the Lead.
A session you make the Lead overwrites the saved one once it has a conversation, and starts without the permissions below. A saved session has permission to move the board or start tickets only if you had already granted it.
Its permissions. Each is separate, and each is off until you turn it on. Moving the board and starting tickets stay through /clear, Bring back and a relay restart, and end when you press their button again or make another session the Lead. After /clear, they are saved again when the brief goes in, so they are lost if the session ends or the relay stops before then.
Its regular check. The relay types a check prompt into the Lead every Lead check every minutes, in Limits and timings under Work (leadCheckMinutes, 5 unless you set it, RELAY_LEAD_CHECK_MS). 0 turns it off. The prompt says it comes from the relay's timer and grants nothing, and asks the Lead to look for a stuck reviewer, a failed pipeline, a PR with no review, or a merged PR whose Dev still holds a desk, and to pass on what it finds. It also tells the Lead not to make its own scheduled check. It comes only while tasks are worked: at least one task is building, in review, has changes requested or is waiting on you. While every ticket is in Triage, Ready or Done, nothing is sent. A check still waiting is taken back at once when the last worked task moves to Done, when you set 0, and when the relay starts with nothing worked or with the check off. It is a saved message for whichever session is the Lead, so it goes in only when the Lead is idle, has had its brief, and has nothing typed in its prompt and no question on screen. A check that comes due while the last one still waits is dropped, not queued, so a busy Lead gets one check when its turn ends, not several. The timer is the relay's (relay/lead-check.js), so the check goes on after /clear, after you make another session the Lead, and after a relay restart, where a check still waiting is kept in RELAY_DELIVERIES_FILE. After a restart, the first check comes one interval after the relay starts.
Moving the board
Until you press Let the Lead move the board in Settings, the Lead cannot move anything. Then it can move tasks and tickets, including accepting from Triage and Merged elsewhere, with relay/ticket.js move, tasks and task (see ticket.js). It still cannot clean up a task or start sessions, except the worker for a ticket it starts. Press the button again to take it back. Taking it back also takes back stopping sessions.
The Lead under Autopilot. While Autopilot is on, only the relay starts and merges work. A Lead keeps three rights: stop a session the Floor calls safe to stop, move a task to Done once its PR has merged, and ask the relay to review a task's PR. The stop is the one in What the Lead stops, with the same switch, verdict and hourly limit. The review is the one in The Lead starts a review, with the same limits, and the Lead may ask for it while Autopilot is on even when Let the Lead start reviews is off. A task's ticket follows it to Done. The relay has seen a PR merge when the task's history says so, or gh pr view said it merged (How the relay hears about PRs). Every other move of a task or a ticket, accepting from Triage, a move to Done before the relay has seen the PR merge, and every start are refused with 403 and autopilot, even when Let the Lead start tickets is on. The relay does not check merges, so the Lead's brief says never merge, even when Let the Lead merge is on. When Autopilot turns on or off, by you or by itself, the Lead gets its brief again with the new words.
The merge rung
The Lead's brief sends it to the merge rung in docs/constitution.md, article 5, which lets it merge a PR with gh pr merge --merge, but only when all of these hold:
- A review of the PR's current head is posted. After new commits, it asks for a follow-up review first.
- Every blocking and fix-now finding is fixed, and the Lead checked each fix in the code. Its brief adds: with no merge hold on the PR's Dev in
ticket.js floor. - The pipeline is green on the current head.
- The base is
mainand GitHub says it merges cleanly. A PR with any other base goes to you. - No decision is left for you, such as a base, a design choice or a security trade-off.
It never merges a PR that changes CLAUDE.md, docs/constitution.md or the lint rules, eslint.config.js and eslint-local.js. When it merges, it says on the PR why and which hand checks are still open, and tells you. Restarting the relay after a merge stays with you. A PR from work it started merges like any other.
There is no button to take this back yet (T-50). Telling the Lead to stop merging lasts only until its next /clear, compaction or Bring back, because each of those types the brief again. The lasting way is a PR that takes the merge sentence out of the brief and the merge rung out of the constitution.
Ready to merge: the note and the label
When the Lead finds a PR ready to merge, it marks it on GitHub. Then you can tell from the PR itself, and from the PR list, that it has been through every review. You do not have to read the whole comment thread. The Lead's brief says to run node relay/ticket.js ready. Run with nothing after it, that prints what to check and what to write, so the brief stays short. The PR watch, when it tells the Lead a PR is ready, names the same command.
What the Lead checks. A review of the PR's current head is posted, every blocking and fix-now finding is fixed and the Lead checked each fix in the code, and no decision is left for you. The relay cannot check these, so the note says how the Lead did.
What the relay checks. Before it posts anything, the relay asks gh pr view and refuses with Not marked: and the reason when any of these fails: the PR is open, its base is main, its head is the commit the Lead named, its pipeline is green on that head, GitHub says it merges cleanly, and its Dev has no merge hold. If the relay cannot read the Floor to check for a merge hold, it refuses too. A note that leaves out one of its three parts is refused as well.
The note. One comment headed Ready to merge. It names the head commit and who merges it, then the Lead's three parts:
Reviews:each review of that head, with its link and verdict.Findings:how each finding was settled: fixed and checked in the code, disputed, or filed as a ticket.Hand checks still open:what nobody has checked by hand yet.
The relay works out who merges it at the time the note is posted, from every file the PR changes or renames, and from the switches then:
- You, when it changes
CLAUDE.md,docs/constitution.md,eslint.config.jsoreslint-local.js, since only a person merges those (article 5). - Autopilot, while it is on and moves the PR's task.
- The Lead, while Let the Lead merge is on and Autopilot is off.
- You, otherwise.
A switch you change after the note does not change the note, so read it as of the time it was posted. The note starts with <!-- office:ready -->, so it is not a review: the Dev is not told about it and its card does not move (How findings get back to the Dev).
The label. The relay adds the ready to merge label, and makes the label in the repo first if it has none. It keeps the PR and its head in RELAY_READY_FILE. Every Check each PR's pipeline every seconds (pipelinePollSeconds) it asks gh pr view for the head again. While that setting is 0, it asks every RELAY_READY_POLL_SECONDS (60) instead, so the label still comes off. When a new commit lands, it takes the label off and says so in #office and in the ticket's chat channel, so the label never points at an old head. The note stays as history, and names the commit it was about. After new commits the Lead checks them and marks the PR again, which posts a new note. A PR that merged or closed keeps its label and is no longer watched. So is one whose label someone took off.
Marking again. A second mark at a head that is already marked posts no second note. It only puts the label back if the label is off. If gh posted the note but could not add the label, the relay still watches that PR, so the Lead can run the same command again to add the label without a second note. Marking and the label check take turns, so a mark made while the relay reads that PR is not undone.
Who can mark. Only the Lead's token, or you with the relay key, through POST /ready. The note and the label go up with your GitHub login, as every session's gh does. Marking merges nothing.
What the Lead sees
The Lead runs node relay/ticket.js floor, which reads GET /floor. Its brief says to run it whenever you name someone, and to answer with the names the Floor shows. Only the Lead's token reads it. It prints one line for each running session the room started. Sessions the page only hears through global hooks, such as one started in another terminal, are not on it.
Theo · reviewer of PR 31 · idle · last hook 20 min ago · safe to stop: its review is posted, idle 20 min
Priya · Dev, T-14 · waiting on the person · last hook 2 min ago · not safe to stop: it is waiting on the person: Claude needs your permission to use Bash
Pam · PM · idle · last hook 45 min ago · not one the Lead may stop: it is the PM
Ada · Dev, T-83, PR 44 · stuck: told 27 min ago and did not start, a menu is open on its screen · last hook 28 min ago · not safe to stop: Enter was pressed 27 min ago and no turn began, so the prompt did not go in
Each line has the name the relay gave that session (see Which person gets it), its role (Lead, Dev, reviewer, PM, or session for a plain one), its ticket and PR, its state (working, waiting on the person, idle, quiet or stuck with how long there was no hook or output, or stuck with how long ago it was told and why), the minutes since its last hook, and whether the Lead may stop it, with the reason. The Lead's own line also says how tired it is. not safe to stop means someone may need it (the verdict below). not one the Lead may stop means the verdict calls it safe, but it is not one of the two kinds the Lead stops, so it is yours to stop. GET /floor has both: safe is the verdict, and canStop is whether the Lead may stop it. A session with no name, as when the relay found no roster, shows as Session and the start of its id, and ticket.js floor adds (no name). Each row also has its desk, which the page draws on the Floor (What each desk says).
A Dev whose PR is open, not merged and whose task is not Done may have a merge hold: why a merge now would leave its work out of the PR (relay/merge-hold.js). ticket.js floor prints it as merge hold: and the reason, and GET /floor has it as mergeHold, or null. There is a hold when an automatic review of the PR was posted with its verdict and no comment check has listed that review yet, so its Dev was not told of it. GitHub may list a new comment a little late, so a check that works but does not list it keeps the hold until a later one does. This hold waits even when the Dev's session has ended, since that check decides what is left. A posted review starts the check at once, rather than at the next poll. With the comment check off (reviewPollSeconds at 0) there is no such hold. There is also a hold when the Dev has review news the relay has not told it yet, when the Dev is working, quiet, stuck, at a question, running a job (such as npm test in the background) or has not begun a turn since the relay last typed a note into it, for up to 15 seconds after the note (RELAY_TOLD_HOLD_MS, the same wait delivery gives a note before it types another), since it may still be answering the latest review, or when its checkout has uncommitted changes (untracked files count) or commits that are on no remote. A checkout that is gone holds nothing. Autopilot asks the same before each merge. The relay does not stop the Lead's own gh pr merge: the hold is in its brief only.
The verdict comes from relay/stop-verdict.js. It never says safe for a session that:
- is working, or waiting on you;
- has text typed in its prompt;
- is still owed its first prompt or brief, or is a task whose brief never went in;
- has the trust question or a menu on its screen (the same checks the relay uses before it types anything,
questionOnScreeninrelay/terminal.js); - had Enter pressed with no hook since, and for 3 seconds after. Once that is past by the relay's check (
RELAY_TOLD_CHECK_MS) too, in a session a hook has reached, it saysEnter was pressed 12 min ago and no turn began, so its first prompt did not go in, orthe promptfor any other; - has been spoken to with no hook heard;
- has its task set to Waiting on you;
- is the Lead;
- is the PM while you talk to it: for 30 minutes after you last typed in it (
RELAY_PM_TALK_MINUTES).
Anyone else idle is safe to stop, with the reason. Safe is not enough for the Lead: see What the Lead stops.
What the Lead stops
A Lead you let move the board can stop one session with node relay/ticket.js stop <who>, where <who> is the name the Floor shows (in any case), a task id, or a desk's id. It works only while Let the Lead stop sessions is on, in Settings, or the relay runs with RELAY_LEAD_STOPS=1. It is off by default, takes effect at once, and a value set in Settings stays through a restart. Taking back Let the Lead move the board also takes this back.
$ node relay/ticket.js stop theo
Stopped: Theo (reviewer, session b299ee24-0c4c-4507-afb7-bb2625eeb192): its review is posted, idle 20 min
To bring it back: Resume with session id b299ee24-0c4c-4507-afb7-bb2625eeb192.
The relay asks the same verdict as the Floor at that moment, and refuses with its reason any session the Floor calls not safe to stop: one that is working, waiting on you (a raised hand, a question or a menu on its screen), the Lead itself, or the PM while you talk to it. A name that fits two sessions, or none, stops nobody.
Then it stops only two kinds of session, whatever the verdict says:
- an automatic reviewer that has posted its review (one the relay started for a PR, which the hook saw post);
- a task's Dev whose PR merged or whose task is Done, with nothing uncommitted in its checkout and no commit that is on no remote. The relay hears that a PR merged from gh, when it checks for the chat board or the pipeline.
It refuses any other session with not one the Lead may stop and the reason: one you just added, a plain session, a reviewer that has not posted (you may be reading its report), a Dev whose PR is still open, a Dev with work that is not pushed, the PM and the COO. Those stay yours to stop. It stops at most 6 sessions an hour on each channel (RELAY_LEAD_STOP_LIMIT), then gives the rest to you.
Stopping is the same as Stop this session on the page. A task worker keeps its checkout and branch, and Bring back on the task returns it in the same conversation. The task's history says the Lead stopped it, and why. #office on the chat board says who it stopped, with the session id, and so do the reply and the relay's log. A session the Lead stopped is not brought back when the relay starts again, the same as one you stopped. One that is not a task's worker, such as the PM or a reviewer, comes back only with Resume and its session id, so the reply and ticket.js stop print it.
Its brief tells it to stop reviewers that have posted and idle Devs whose PR has merged, and to tell you who it stopped. The relay holds it to those kinds and checks that nobody is waiting on them.
The Lead starts tickets
Only you start tickets until you let the Lead. In Settings, pick two numbers beside Let the Lead start tickets and press it. The first is how few tasks must be building for the Lead to start one, from 1 to one under the WIP limit (RELAY_WIP_LIMIT, 3 unless you set it), so 1 or 2 with the usual limit. The second is how many it may start in all, from 1 to 20 (POST /terminals/lead with starts and total). The Lead then runs node relay/ticket.js start T-4, and the relay refuses a start, with the reason, unless all of these hold, whatever the brief says:
- The ticket is in Ready, and a person put it there: you filed it from the Board, or pressed Approve. The relay keeps who moved each ticket to Ready (
approvedBy), so a ticket the Lead approved itself waits for you. Leaving Ready clears it (none), so a ticket put back in Ready outside the relay, such as by a label on GitHub, waits for you too. A ticket you file on GitHub has no approval. A ticket from before this was kept counts only if you filed it from the Board. A Ready card with no approval from you, for any of these reasons, says "not approved by you". Approve all Ready above the Board approves the ones it lists, after a second press that names them (POST /tickets/approve-readywith theirids, which needs the relay key). A ticket that reached Ready after the button was drawn, or is starting, is left for the next press. Reject first any you do not want built. - It is the next such ticket in Board order: high before normal before low, and in work order within a priority. A ticket that waits for another, names no repo, or is on hold, replaced, or waiting on a design ticket, is skipped, and the relay refuses to start it if the Lead names it.
- Every ticket it waits for is done. A rejected blocker, or one not on the Board, leaves it for you.
- The worker on the last ticket the Lead started has picked up its brief, or has stopped, so it starts one at a time. A start that is still under way counts too, so a burst of starts gets one through.
- Fewer tasks are building than your first number, counting the ones you started. This is checked again in the moment the task is counted (
relay/tasks.js), so it does not rest on the Lead's brief. - Autopilot is off. While it is on, only the relay starts work (The Lead under Autopilot).
Each start uses one of the total. The last one turns the permission off, and the panel says so. The task records by: "Lead", and its card on the Board says started by the Lead with the time. The Board's header shows your number and the starts left. The Claude Code panel announces each start with the ticket and the starts left, from the Lead's lastStart in GET /terminals, and the relay's log says The Lead started T-4. The panel tells only a page that is open, so the Board's cards are the record.
Stop the Lead starting tickets takes it back sooner. The Lead starts nothing more, and work it started keeps running. Like moving the board, it is a separate permission, and stays through /clear, Bring back and a relay restart, with the starts left. It ends when another session is made the Lead. A number saved at or above a WIP limit you lowered since comes back off. relay/test/lead-start.test.js checks each rule.
Refreshing the Lead
A long conversation gets compacted, and each time the Lead keeps only a summary of it. Refresh the Lead keeps its conversation small. It is in Settings while a session is the Lead, and sends POST /terminals/lead with {"refresh": true}. The relay runs the steps in relay/lead-refresh.js, driven by the Lead's hooks, and types each one with the same checks as any message it types (notSafeToType, see how the relay types): the Lead's turn has ended, no brief is owed, nobody has text in its prompt, and no menu is open.
A Lead that still owes its brief. If the Lead has not had its brief yet, the button types the brief now instead, with the same checks as a first brief: it does not wait for an update's quiet moment, but it waits while the relay restarts, and it types nothing while the Lead is working or waiting on you, a question or menu is on its screen, someone has text in its prompt, or its screen shows no prompt. The refresh stops there, and the page says so: press the button again later if the Lead still needs a refresh. If the brief cannot go in, the answer says why in plain words, such as The Lead has not had its brief, and the relay cannot type it now: its screen shows no prompt. The brief still goes in by itself once it is safe.
- It asks the Lead to rewrite its handoff notes in
lead-notes/notes.mdin the relay's state folder,~/.office-world/lead-notes/notes.mdby default. - Once that turn ends, it types
/clear. The Lead keeps its role and its permission to move the board. - The relay types the brief again, as it does after any
/clear. - Once that turn ends, it asks the Lead to read the notes back and carry on.
The steps start only when the Lead is idle, has had its brief, and has nothing typed in its prompt. One refresh runs at a time. It ends when the Lead's session ends, when another session is made the Lead, after 15 minutes, or when you press Stop the refresh ({"refresh": false}), which is what the button reads while it runs. That stops it before the next step, and what was typed stays typed. A prompt you send to the Lead during a refresh is answered first. An update waits for a refresh to end before it restarts the relay. GET /terminals shows each session's refresh (the step it is on, or null), refreshNote (how the last one ended) and tired (see How tired the Lead is).
The notes are context, not permission. They keep only what the board, the pull requests and a huddle cannot show: your decisions, the Lead's promises, and why something waits. They copy no live state, which would go stale, and they grant nothing, since any session could write that file. The fresh Lead drops lines that no longer hold, and checks with you any line that reads like a permission. What lived only in the old conversation and is not in the notes is gone.
How tired the Lead is
Tired means how much of its context window the Lead has used since its last /clear or refresh. The fuller it is, the sooner Claude Code compacts the conversation by itself and the Lead keeps only a summary, which is when it slows down or forgets a decision. You see the level in three places, and they all read the same number:
- On the Floor. The Lead's row in the people list shows the level with its icon. Hover over it for the percentage. Before the Lead's first reply in a conversation it says Context use not known yet. In Settings, hovering over Refresh the Lead says the same.
- In the Lead's own terminal. Its status line, under its prompt, says for example
◑ context 62% · getting tired. - From the Lead. Ask it how tired it is. Its brief says to run
node relay/ticket.js tired, which reads the number from the relay.ticket.js floorshows it on the Lead's line too.
| Level | Context used | What it means |
|---|---|---|
○ fresh | below 50% | Nothing to do. |
◑ getting tired | 50% to 69% | A refresh is coming. Plan one for a quiet moment, when the Lead is idle. |
● needs a refresh | 70% and over | Press Refresh the Lead when the Lead is idle. It writes its notes, gets a new, small conversation, and reads them back, so it comes back fresh. |
A refresh starts only when you press the button: nothing starts one at a level. The levels are in relay/lead-tired.js. The number comes from Claude Code itself. Every session the room starts gets the room's status line, relay/status-line.js, in its --settings. Claude Code runs it after each change in the session and hands it context_window.used_percentage. The status line prints the level and sends the number to the relay with the session's own token (POST /terminals/context). The relay keeps it with the session, for the conversation it was sent from, so after a /clear the old number is gone until the new conversation's status line sends one. Like the hook, the status line gives up on the relay after one second and still prints. The room's status line takes the place of any status line of your own in the sessions the room starts. The Floor shows the level for the Lead only.
Settings
The switches for what runs without you are in one dialog. Press Settings in the room bar to open it. On the left of the bar, four chips say which are on, such as Autopilot off, Lead: board, merge, Reviews: auto and Huddle: tells the Lead (or Huddle: Floor only). A chip is outlined in green while what it names does something without you. Pressing a chip opens Settings at that section. Each switch has a line under it saying what it does. They work whichever session the panel shows. While the dialog is open, what a press did shows at its top.
- Trust level. The rungs of article 5 of the constitution, as six levels. Each is a set of the switches below:
Every other switch is off at each level. Picking a level says which switches it turns on and off. Nothing changes until you press Set level. Then the page sends the same request as pressing each switch, the ones going off first, and stops at the first one the relay refuses, saying why. Levels 2 to 4 need a Lead. Level 5 does not: with no Lead, Let the Lead move the board stays off, and the switches still match level 5. The level the switches match now is marked, or custom when they match none, for example after the Lead's starts run out. Part of rung 1, where findings go back to the Dev, is always on: level 1 adds the follow-up reviews, with their limit of 3 for each PR. Rung 5, a monitor, is not built.Level Turns on 0. You drive Review PRs automatically 1. Review loop (rung 1) and Review again after each push 2. The Lead keeps work moving (rung 2) and Let the Lead move the board and Let the Lead stop sessions 3. The Lead starts tickets (rung 3) and Let the Lead start tickets, with the two numbers beside it 4. The Lead merges (rung 4) and Let the Lead merge 5. Autopilot (rungs 3 and 4, run by the relay) Review PRs automatically, Review again after each push, Let the Lead move the board, Let the Lead stop sessions and Autopilot. Only the relay starts and merges work. A Lead keeps three rights: stop a session the Floor calls safe to stop, move a task to Done once its PR has merged, and ask the relay to review a task's PR. See The Lead under Autopilot. - Reviews. Review PRs automatically and Review again after each push.
- Autopilot. The Autopilot switch, the box of tickets it may start, and what it is doing now.
- The Lead. Who the Lead is, and Let the Lead move the board, Let the Lead stop sessions, Let the Lead set priority (off by default), Let the Lead start reviews (off by default), Let the Lead merge, Let the Lead start tickets and Refresh the Lead. With no Lead, it says how to choose one: Make this the Lead stays in the panel, since it is about the session on screen.
- Huddle. A line on what a huddle is, and Send each status report to the Lead (one Lead turn each), on by default. This one switch is kept in this browser, not by the relay, as it was when it sat on the Floor. Its chip is never outlined, since it does nothing without you pressing a huddle button.
- COO and PM. Let the PM set the order, off by default, under Limits and timings.
- PR watch. Watch each open PR, off by default, with how often it looks and how long a PR may wait before it waits on you, under Limits and timings. The trust levels do not change it.
- Limits and timings. The WIP limit, how often the relay sends the Lead its check, how many automatic reviews a PR gets, Autopilot's rounds and merges a day, and the relay's timings, each with what it does. See Settings you change while it runs.
Except the Huddle switch, which this browser keeps, the relay keeps every switch and value, so each holds with the page closed and after a restart, and applies at once.
Sessions can list and file tickets, and only a Lead you chose can do more
Each session the room starts gets a token good only for that, used by relay/ticket.js. A Lead's token can do what you let it do, and so can a PM's token while Let the PM set the order is on, and nothing else. While Let the Lead set priority is on, the Lead's token can also set priority and order (see which routes each token reaches). Sessions run with your normal permissions, and one could read the relay key from your hook settings, so this is a check on process, not a security boundary.
Autopilot
With Autopilot ticked (it starts unticked, and the relay keeps it in RELAY_AUTOPILOT_FILE), the relay takes tickets from Ready to merged by itself, with nobody pressing anything (relay/autopilot.js, rules in relay/autopilot-plan.js). It is rungs 3 and 4 of article 5 together, in the constitution. The box under it in Settings limits it to the tickets you list, such as T-12, T-15, to the tickets with a label you list, such as flaky, or both, such as flaky, T-12. A label lets in every ticket that has it, also one you label while Autopilot runs, and still only the Ready tickets a person approved. Only you set labels, so no session can add a ticket to the list. Leave it empty for every Ready ticket. When you turn Autopilot off, the list is cleared, so a list is for one run only. When Autopilot turns itself off, it keeps the list. When a list is set and no ticket on it can start, the line next to the switch says why each one in Triage or Ready waits, and names each one rejected, in Board order, such as No ticket you allowed can start. T-12: On hold. T-15: Waiting for T-9. The reasons are Rejected, In Triage, Not approved by you, Waiting for its blockers, the hold, replacement or design ticket, and No repo. Only when every ticket on the list is started or done does it say Every ticket you allowed is started or done., and when no ticket has an id or label on the list, it says so. Every RELAY_AUTOPILOT_TICK_MS (20 seconds) it does this:
- Start. While fewer than
RELAY_AUTOPILOT_AT_ONCEtasks (1) are open, it starts the next Ready ticket that a person filed or moved to Ready, whose blockers are all done, and that is not on hold, replaced, or waiting on a design ticket, in Board order. While the latest CI run that a push to that ticket's base branch started failed, it starts nothing, and the line next to the switch says Main is red, so T-5 waits: and which run failed (A red main). The task says it was started by Autopilot. A task is open until it is Done or Waiting on you. Its own count is only of tasks it started, while the WIP limit counts every task being built. So when tasks you or the Lead started fill the WIP limit, Autopilot waits, says Waiting for room under the WIP limit in Settings, and starts the ticket once a task finishes. It does not turn itself off for this. While an automatic review waits for a desk, it starts nothing, and the line next to the switch says Waiting for a free desk: the review of PR #N goes first., since a review frees the desk it needs by itself (A review frees a desk). If the start fails because all 9 desks are taken, it waits up to 5 seconds for a session that is already ending, and tries once more. If none ends, it stops one of its own sessions that the Lead may stop (the same verdict): the Dev of a task it started, whose PR merged or whose task is Done, with nothing uncommitted or unpushed in its checkout, or a reviewer that has posted on the PR of such a task, automatic or from Get a review. It waits up to 5 seconds for that one to end, then tries once more. It stops the one idle the longest, and only one, since a start needs one desk. If the WIP limit fills while it frees a desk, so the next try is refused for it, that is the same wait for room under the WIP limit. Its note, the chat and the task's history say who it stopped and why. It never stops a session on a task it did not start, so those stay yours. Let the Lead stop sessions and the Lead's hourly limit do not apply. When no desk comes free, that is a wait, not a failure, as for the WIP limit. Autopilot stays on, and the line next to the switch says what it waits for, such as Waiting for a free desk: 9 of 9 taken, none safe to stop. The reason can also be that a session did not end in time, or that another session took the freed desk first. It writes one note when the wait starts, not one at each look. At each look it goes through the same steps again, and starts the ticket as soon as a desk is free, such as when a session ends. There is no time limit on the wait. - Review. The Dev opens the PR, and the first review starts as in Automatic review. While Autopilot is on, every push to a reviewed PR also gets its follow-up, as if Review again after each push were ticked. Each review of a PR, automatic or from Get a review, with Autopilot on or off, asks the reviewer to mark each finding with one of three kinds, blocking, fix now or follow-up, and to run
ticket.js verdict mergeorticket.js verdict fixbefore it posts. It says merge only when no finding is blocking or fix now. A verdict from Get a review counts like any other: when it says merge, the checks passed and GitHub can merge the PR, Autopilot merges it. - Fix once. Review comments reach the Dev as before. The Dev fixes the blocking and fix-now findings together, and pushes. A follow-up review checks only the commits since the last review that was posted with a verdict, and for a merge of main only how its conflicts were resolved. With no such review yet, it reviews the whole PR.
- A Dev that is not running. When the latest posted verdict says fix for the PR's head, or GitHub reports a conflict with main, and the task's Dev is not running, such as after a stop before a relay restart, Autopilot brings it back as Bring back does: the same checkout and the same conversation. The saved review news, or the ask to merge main, then goes in. Its note says its Dev was not running, so Autopilot brought it back for the fixes the last review asks for, or for a merge of main. A Dev that pushed after the fix verdict and then ended is not brought back: the follow-up review checks its commits. While the WIP limit is full or every desk is taken, Autopilot waits, says why next to the switch, and tries again at each look. If it cannot bring the Dev back for another reason, such as a checkout that is gone, or if the Dev it brought back for that same commit is not running again, the task goes to you with the reason and the step: press Bring back on its task, then move its card back.
- Merge. It merges with
gh pr merge --mergewhen the latest posted verdict says merge for the PR's current head, every check on that head passed, and GitHub can merge it. It names that commit with--match-head-commit, so GitHub refuses the merge if a commit arrived since it looked. First it asks whether the PR holds all its Dev's work (the merge hold). While no comment check has listed its latest posted review, while the Dev has review news it was not told, or while it is working, quiet, stuck, at a question, running a job, or told something in the last 15 seconds it has not started on, Autopilot waits, since the Dev may still be answering the latest review. Once the Dev is idle or gone, uncommitted changes or unpushed commits in its checkout send the task to you, and so does review news its ended session was never told. A branch behind main is fine, since main does not ask for branches to be up to date, so nobody merges main into a PR for that. Just before it merges, it reads the PR's comments once more (How findings get back to the Dev): if they could not be read, it waits for the next look; if they hold a Dev's reply with<!-- office:hold -->, the task goes to you; if they hold new review news, the Dev hears it first. If GitHub reports a conflict, it asks the Dev to merge main, keep both sides, and push only that merge, not fixes for the review's non-blocking findings. That push gets a follow-up review. If a turn of the Dev begins after the ask went in and ends, and the PR still conflicts at the same head, Autopilot asks once more at its next look, and its note says its Dev was asked once more. If a turn ends after that second ask too, the task goes to you: Its Dev was asked twice to merge main into PR #N at <commit>, and each turn ended without it. A new head starts the count again. It does not wait for the stall time (autopilotStallMinutes) for this. - Done. Once the PR has merged, its task goes to Done, its ticket follows, and the Dev's session stops if it is not in a turn. A Dev still in a turn then may be stopped later, while Autopilot is on and a start needs its desk. The relay then pulls main into its own folder, as Update does, and restarts once no session is busy if relay files changed. While that update waits for a quiet moment, Autopilot goes on: it still reads PRs, merges, moves tasks and starts tickets. A new Dev gets its brief at once: an update holds a task's brief only while the relay restarts, and then waits for that Dev's turn too. Other saved messages, such as review findings for a Dev, are held only for the first 10 minutes of the wait (While an update waits). A PR it merges in that wait is pulled into the same update, so the restart runs it too. Autopilot stops only once the restart itself begins.
It hands a task to you, in Waiting on you with the reason on the card, and then leaves it alone, when:
- the second posted verdict still says fix (at most 2 review rounds);
- the PR changes, renames or removes
CLAUDE.md,docs/constitution.md,eslint.config.jsoreslint-local.js, which only a person merges (it reads every file of the PR through the GitHub API). So that code does not wait with them, these changes go to one grouped ticket. For this one, Autopilot keeps the reason up to date until you merge (A PR only you merge); - its task is stuck for
RELAY_AUTOPILOT_STALL_MS(30 minutes, Give you a stuck task after in Settings) at a session: its Dev or a reviewer of its PR has been at a question or a permission prompt that long, or stuck with no hook and no output that long, or a reviewer has not started on its brief in that time. A quiet session, with no hook but output still moving, may be thinking, so its task stays (a brief is not counted while the relay restarts, since nothing types it then). See A stuck session below; - nothing could move it for
RELAY_AUTOPILOT_STALL_MS(30 minutes): no reviewer running, no review waiting for a desk, its Dev idle or gone, and not waiting on CI, GitHub or the day's limit (a PR that GitHub still shows open after Autopilot merged it does count), as when a review was posted with no verdict, or the Dev stopped without opening a PR. A Dev running a job, such as tests in the background, is busy, not idle. A Dev that is idle with no PR is nudged once first. See When nothing moved it below; - a check failed on the reviewed commit, the PR was closed, or
gh pr mergefailed; - its Dev is not running and Autopilot could not bring it back;
- the PR is ready to merge, but its Dev is idle or gone with uncommitted changes or unpushed commits in its checkout, or with review news it was never told (the merge hold).
Autopilot works only on tasks it started. A task it handed to you stays yours, even when the relay moves its card for a new review comment. Until you move the card, its desk on the Floor says Waiting on you: and Autopilot's reason, with the link to the comment when a Dev's reply with <!-- office:hold --> held it, such as Its Dev says a finding the review marked non-blocking is a bug and the link. Its status says waiting on you, and Needs you lists it. Neither shows what GitHub last said about the PR, such as GitHub says the PR is unknown, since that is not what waits, except for a PR only you merge. Move the card yourself and Autopilot takes it back, with its review rounds counted from 0 again. For a hand-over from a Dev's reply with <!-- office:hold -->, that means merge it: the hold works once, and if the latest merge verdict still covers the PR's head, Autopilot merges on it at its next look, with no new review. To have the finding fixed first, tell the Dev, or leave the card where it is. Autopilot also takes it back by itself when a newer commit answers the hand-over. This happens when a review of a newer commit than the one handed over is posted with a merge verdict, and the hand-over came from CI that failed on the reviewed commit, or from a Dev's reply with <!-- office:hold -->. For a Dev's reply, the newer commit must also hold a commit of the branch's own that is not a merge, since a merge of main does not answer the finding. The reviewer's checkout tells which, when it gives its verdict. The card goes back to In review, a note says which commit the review read, and Autopilot merges as usual. A merge review of the same commit keeps the hand-over, and so does one of a merge of main after a Dev's reply. Any other hand-over, such as one for too many review rounds, waits for you to move the card. If you merge its PR instead, Autopilot still marks the task Done and frees its Dev's desk, as for any other of its tasks. A verdict counts only once its review is posted (see Reviewers leave), and only for the commit the reviewer's checkout is at. A review posted with no verdict does not count, automatic or from Get a review, and the next push brings another. A verdict comes only from a reviewer's own token: a Dev cannot give one. It merges at most 10 PRs a day, then waits for tomorrow or for you. It merges each PR once and counts it once. While GitHub still shows a PR open just after Autopilot merged it, Autopilot leaves it alone. If that lasts RELAY_AUTOPILOT_STALL_MS (30 minutes), the task goes to Waiting on you. If it cannot start a ticket for any reason but a full WIP limit or a full Floor, it turns itself off and says why. Turning it off stops nothing that is under way. What it is doing shows next to the switch, and in GET /autopilot, which only the room page reaches.
A PR only you merge. A PR handed to you only because it changes CLAUDE.md, docs/constitution.md, eslint.config.js or eslint-local.js still gets its reviews, and Autopilot keeps looking at it at each look. It never merges it. Its reason on the card, in Needs you, next to the switch and in the task's history follows the PR: It changes CLAUDE.md, which only a person merges. Waiting for its review., then The review of 0fdd14b says fix, so its Dev fixes it first., Waiting for a review of the new commits., Waiting for CI., CI failed on the reviewed commit., GitHub says the PR is blocked., or The review of 0fdd14b says merge, but it conflicts with main. Once the latest posted review says merge for the PR's current head, every check on it passed, GitHub can merge it, and the PR holds all its Dev's work, the reason says Ready for your merge: the review of 0fdd14b says merge, CI is green, and GitHub can merge it. That is the same test Autopilot uses before its own merges. Autopilot's note says it once for each head, and the room page says it once for each head in the status line under the Floor, also after a reload. A new push takes the reason back to waiting for a review. The task stays in Waiting on you the whole time. When you merge the PR, Autopilot marks the task Done. GET /autopilot gives the PR a ready with the head commit while it is ready, else null.
A stuck session. When a task goes to Waiting on you because its Dev or a reviewer is stuck, the card and Autopilot's note say which session and why, such as Its Dev Ada at a question (Claude needs your permission to use Bash) for 30 minutes, or Its Dev Ada has sent no hook and printed nothing for 30 minutes. Autopilot does not stop that session: it stays open at its desk, so you can look at it and answer it there. In Waiting on you the task no longer counts toward Autopilot's tasks at once or the WIP limit, so Autopilot starts the next Ready ticket. Desks are the real limit: the stuck session keeps its desk, and once every desk is taken Autopilot waits as it does for any start. When you answer and the session moves again (a hook says it did something, and it is not at a question), Autopilot moves the task back to where it was, Building for a Dev, and takes it back, even if that is over the WIP limit for a while. The session never left its desk and is at work again, so the limit does not hold the task in Waiting on you. It holds only Autopilot's next start, until fewer tasks are being built than the limit. Its review rounds are not counted again. If you move the card yourself first, the task is yours to move, as for any task Autopilot handed to you. Autopilot looks for this only while it is on. If an update restarts the relay before you answer (it does not wait for a session at a question), the session stays at its question in the session host, and you answer it there as before. If the relay is stopped before you answer, the session comes back with its conversation but without its question, and sends no hook until it gets a prompt. So the task stays in Waiting on you: tell the session to go on, and the task comes back once it moves, or move the card yourself. The note on the card says so. A reviewer that the relay typed its brief into, but whose hooks never reach the relay, is not counted as one that has not started.
A nudge before it parks. When a task has no PR and its Dev has been idle for RELAY_AUTOPILOT_STALL_MS (30 minutes), Autopilot does not hand it to you at once. It sends the Dev one saved message: Your task has no PR yet. If a test run was lost, run it again in the foreground and open the PR. If you are blocked, say why. Its note says Autopilot nudged its Dev, which stopped without a PR. The task then gets one more stall time. If the Dev is still idle with no PR at the end of it, the task goes to Waiting on you, and the card says what is true: its Dev has been idle for 30 minutes with no PR, and did not start a turn after Autopilot nudged it 30 minutes ago, or and took a turn after Autopilot nudged it 30 minutes ago if it took one. The minutes since the nudge count from when it was typed in. A saved message is typed only when the session is safe to type into, so a nudge can expire unsent, and then the card says and the nudge Autopilot saved for it 30 minutes ago was never typed in. The idle minutes count from the Dev's last hook, or from when its session started if it has sent none. Only a Dev whose session has ended is not nudged, and the card says so: its Dev's session ended, and there is no PR. A Dev running a job, at a question or in a turn is not nudged. There is one nudge per task each time it stalls, and a relay restart does not send a second one. Autopilot forgets the nudge each time it sends the task to Waiting on you, for any reason, such as a Dev at a question. So when the task comes back and stalls again, the Dev is nudged again.
When nothing moved it. A task that went to Waiting on you because nothing moved it comes back to Autopilot by itself as soon as something does, after the move to Waiting on you: its Dev opens a PR for it, its Dev sends a hook that says it did something (and it is not at a question), or a review of its PR is posted with a verdict. The task goes back to where it was, Building for a Dev, even if that is over the WIP limit for a while, as for a stuck session, and Autopilot reviews and merges it as usual. The card and Autopilot's note say why, such as its Dev opened PR #153, so the task is back, its Dev Ada moved again, so the task is back, or a review of PR #153 was posted with the verdict merge, so the task is back. Its Dev is the session at its desk now, which can be one you brought back. If you move the card yourself after the move to Waiting on you, the task is yours, as for any task Autopilot handed to you. Autopilot looks for this only while it is on. The COO counts such a task as no wait on you.
What it keeps of each run. For each ticket Autopilot starts, the relay keeps one run record in RELAY_AUTOPILOT_FILE, so it lasts through a relay restart and is not cut like the notes, which keep only the last 30 lines (relay/autopilot-runs.js). A record has the task and ticket ids, the ticket's kind when it started, and the PR link. It has the time of each step, each kept once: when the task started, when its Dev got the brief, when its PR opened, each posted verdict with its commit and time, when it merged and whether Autopilot or a person merged it (a merge Autopilot did not make is a person's, also when the task reached Done by another move), and when it went to you, with a reason word. The steps come from the task's history and from Autopilot's own merges and hand-overs. While Autopilot is off, a record is filled in at its next look once it is on again. A record holds no key, prompt, ticket title or ticket body: only ids, times, verdicts and reason words from a fixed list. Each record is kept for 90 days from its start, then dropped at the first look of a new day. Its outcome is one of the four that article 5 names for rung evidence, in this order:
- manual: Autopilot handed it to you by rule, such as a PR that changes
CLAUDE.mdor the constitution, CI that failed, review rounds at their limit, a merge that failed, work left out of the PR, or a Dev that says a finding is a bug. A PR a person merged is manual too. - blocked: it went to you because something was stuck: a session at a question, a session silent for too long, a reviewer that did not start on its brief, nothing that moved it, a brief its Dev never got, a Dev that was not running and could not be brought back, or a Dev that did not merge main after two asks. A task stays blocked even if it came back and merged.
- flawed: a review said fix, or a fix was needed after the merge. A fix after the merge is a ticket of kind
bug, filed or given that kind after the merge, whose title or body names the run's ticket id or its whole PR link (the link to PR 4 is not named by the link to PR 44), and not filed by that run's own Dev. The time is when the ticket was filed, or when you gave it the kindbug. A kind given later does not say who filed the ticket, so a ticket its own Dev filed with no kind counts once you mark itbug. - success: Autopilot merged it, and none of the above.
A run with none of these yet is open. Next to the switch in Settings, the line says how the runs started today ended so far, by outcome and by ticket kind, and the median minutes from start to merge of today's runs that merged. A ticket with no kind counts as none. Today is the day in UTC, as for the day's merges. GET /autopilot has the same in runs.today, and the last 10 records with their outcome in runs.recent.
The PR watch
With Watch each open PR on, in Settings under PR watch, the relay keeps each open task PR moving by reading where it stands on a timer, not by waiting for a hook (relay/pr-watch.js, rules in relay/pr-watch-plan.js). It is off by default. The relay keeps it in the settings file, so it stays off after a restart until you turn it on, and it stays on until you turn it off. A missed hook, a closed page, a relay restart or a push the relay did not hear then costs one look, not a night. It merges nothing.
Every Watch PRs every seconds (120, RELAY_PR_WATCH_SECONDS), and 5 seconds after the relay starts, it reads each task that has a PR and is not Done: the PR from GitHub with gh pr view (its head commit, its checks, and whether it merges cleanly), what the relay keeps about its reviews and their verdicts, its Dev's session, and the commits in its Dev's checkout that the PR does not have. A PR that merged or closed is dropped. It then decides who owes the next move, in this order, and acts on it:
- Its task is in Waiting on you: it waits on you, and the watch does nothing. A task Autopilot started, while Autopilot is on, waits on Autopilot, and the watch leaves it to Autopilot.
- Its Dev's checkout has commits the PR does not have (past the PR's head, or on no remote when git does not have that commit), and the Dev is idle: the watch tells the Dev to push them with a plain
git push. This comes before a review, which would read code that is about to change. With the Dev's session gone, it waits on you. - Its Dev is at work: it waits on the Dev. At a question, or stuck: it waits on you, and the Dev is not told anything more.
- It conflicts with main, or a check failed on its head: the watch tells the Dev. A failed check that the relay already told the Dev about, while its review waited on the pipeline, is not told again. Checks still running: it waits on CI.
- No review read its head, and none runs: the watch asks for one, as if the PR's hook or push had been heard. A PR the relay has no review record of, such as one opened while the relay was down or before it kept records, gets its first review. One with a record gets a follow-up, even while Review again after each push is off. Each counts against the automatic reviews per PR (3): past that, or with Review PRs automatically off, it waits on you.
- The review of its head has a verdict that asks for fixes: the watch tells the Dev to fix each blocking and fix-now finding and push, and not to push for its follow-up findings. A review with no verdict waits on you. A verdict given but not posted waits on the reviewer.
- The review of its head says merge, its checks are green, and GitHub says it merges cleanly: the watch tells the Lead, which checks it and marks it ready to merge, then merges it if it may (the merge rung), or tells you it is ready. It waits on the Lead while a Lead runs that may merge, and on you otherwise. A PR that changes
CLAUDE.md,docs/constitution.md,eslint.config.jsoreslint-local.jswaits on you, and the Lead is not told.
Each message is a saved message, so it goes in only while the session is idle. After it goes in, the relay checks that the Dev started a turn, and if not, the Dev shows as stuck. Each action is kept by PR, head commit and cause, in ~/.office-world/pr-watch.json (RELAY_PR_WATCH_FILE), so the next look, and a look after a restart, does not do it again. A new head starts afresh. A push is kept by the commit to push too, so new local commits are told again.
Each PR has one line: who it waits on, and for how long. ticket.js floor prints it on its Dev's line as PR waits on the Dev for 12 min: and the reason, GET /floor has it as waitsOn, and the PR's ticket card on the Board says it too. The wait counts from when the owner or the reason last changed, and starts again after the watch was off. A PR that waits on its Dev, a reviewer, CI or the Lead for Give you a PR that waits after minutes (60, RELAY_PR_WATCH_WAIT_MS) waits on you, and its ticket's chat channel and #office say so once for that head and reason.
The answers to article 5's five questions, for this switch:
- What starts it? The relay's timer, while you have the switch on.
- What does it read and write? It reads each open task PR with
gh, the relay's review and verdict records, the Dev's session and its checkout withgit. It writes a saved message to the Dev or the Lead, a review request to the automatic reviews, a post on the chat board, and its own record. - What does it start next? At most one review of a PR's head, within the limit on automatic reviews. Nothing else: a message starts no session, and it merges nothing.
- Where does the person come back in? The line on the Floor, the Board and
ticket.js floor, every PR that waits on you, the chat post when a wait goes to you, and the switch. - What stops two sessions from doing the same work? Each action is done once for each PR, head commit and cause, kept through a restart. A review is asked for only when no review read the head and none runs, and the automatic reviews count it. A task Autopilot moves is left to Autopilot.
Reviews
Automatic review
The relay starts the automatic reviews (relay/reviews.js), so they start with the room page closed. With Review PRs automatically ticked (it starts ticked, and the relay keeps it in RELAY_REVIEWS_FILE), a session that opens a PR with gh pr create gets a second worker, titled "Review PR #N", who posts a PR comment. They work in a copy of the repo at the PR's latest commit (relay/checkouts.js), which goes away when their session ends, if they left nothing in it. If they did, it waits in the panel for Clean up, the panel says what is in it, and any commits are kept on a branch kept-<id>. A Clean up pressed just as the session ends waits until the relay has looked, so the two never both remove the copy. If the relay stopped first, the copy goes at the next relay start, under the same rule.
It only starts if all of these hold at that moment:
- The relay runs with the terminal on, as with
npm run office. - The relay has no record of a review of the PR yet, automatic or from Get a review.
- The PR is of a repo the room works in. A session the room started counts for any PR it opens. A session the room did not start, such as one in your own terminal with the global hooks from
npm run office:hooks, counts only for a PR of a repo the room has a clone of: the folder the relay runs from, or a repo a ticket names, with a remote that is the PR's repo. The relay ignores any other PR: no review, no line on the panel or the Floor, and no message to you or the Lead. The relay's log saysPR … is not of a repo the room works in, so it gets no automatic review. - The PR can be fetched. If not, the message says
Could not fetch …. When git fails withbad object refs/…, the message also names the file of that broken ref, so you can remove it. One kind the relay takes away itself: a ref whose name ends in a space and a number, such asrefs/stash 2. iCloud or Finder makes such a copy of a ref file in a synced folder, such as~/Documents. Git cannot read a ref name with a space, so it fails on the copy even when the commit it holds exists. If that commit is missing, or another ref already reaches it, the relay deletes the file, and its log saysRemoved …, a copy of a ref that iCloud or Finder madeand the commit. Otherwise the copy may hold the only pointer to a commit, such as one from a sync conflict with another Mac. Then the relay moves it to a valid name underrefs/office/rescued/, with the space made a dash, as inrefs/office/rescued/stash-2, sogit gccannot prune the commit. The log saysMoved … to refs/office/rescued/…, and so does the error if the review still cannot start. Look at the commit withgit log refs/office/rescued/stash-2, and delete the ref withgit update-ref -donce you no longer need it. A copy that holds no commit hash and noref:line, such as one a sync cut short, is kept, since the relay cannot tell what it held: the error names its file, as for any other broken ref. Then the relay tries the fetch again. It does the same when it makes the review's checkout. - The folder is a clone with a remote at GitHub:
github.com,ssh.github.comon any port, or an SSH host alias thatssh -Gsays stands for one of them, as ingit@github-work:owner/repo.git. If no remote is the PR's repo, as in a clone of a fork with onlyorigin, or a remote using the repo's old name, the PR is fetched from the PR's own repo. The relay writes that address the way each GitHub remote is written, so the same key or login works, then trieshttps://github.com/owner/repo.git. Git asks for no password on the way: a private repo needs a key or a credential helper that already works. That fetch brings the PR's commits into the clone. If no remote of the folder is the PR's repo, or the folder is no git repo at all, as when a session in another project's folder opened the PR withgh pr create -R, the review uses the room's own clone of the PR's repo instead: the folder the relay runs from, or else the first repo a ticket names, if it has a remote that is the PR's repo. The relay's log says… is not a clone of owner/repo, so the review of … uses …. Follow-up reviews do the same. With no such clone, a PR that shares no history with the folder gets no reviewer, and the message saysshares no history. So does a clone with no commits yet, before anything is fetched, and its message saysno commits yet. An automatic review refused withshares no historyis not tried again and does not wait on you: the relay drops it. The relay's log says why, and the panel saysNo review of PR #N: it is of another project., so the line that said its review starts does not stand. Messages and the relay's log show each address with nothing before its@, so a token in a remote's address stays out of them. Every fetch for a review, from a remote or an address, asks for no password and gives up after 30 seconds. ssh asks nothing on the relay's terminal either, neither a key's passphrase nor whether to trust a host it has not seen: the relay gives ssh an askpass that always says no. So a key with a passphrase works only through an agent or the keychain, and a host alias whose host is not yet inknown_hostsfails until you connect to it once yourself, as withssh -T git@github-work. If you set anSSH_ASKPASSof your own, ssh uses it in place of the terminal, unless yourSSH_ASKPASS_REQUIREsays otherwise. This needs OpenSSH 8.4 or later. An older ssh can still ask on the terminal, until the 30 seconds run out. One that waits for each address in turn can keep Update waiting forA new checkoutthat long. - The session's hooks reach the room. Sessions started on this page get hooks of their own, unless
~/.claude/settings.jsonalready has the room hooks. Then they use those, and so do sessions from your own terminal, which need them fromnpm run office:hooks. Hooks with an old key report nothing: see the common messages.
It also waits for the PR's pipeline to be green, as in A clean pipeline before review. It starts once per gh pr create, and the relay keeps a review that could not start, so a restart keeps it too:
- No desk free. The panel says No desk is free for the review of PR #N. It starts once a desk is free. The relay looks every second, and starts it when a desk is free. It waits as long as it takes, and is not counted as a try. The Floor says
review waits for a desk, and the next stepThe review of PR #N starts when a desk is free. See A review frees a desk for how it gets one. - Any other reason, such as a PR that cannot be fetched. It tries again a minute later (
RELAY_REVIEW_RETRY_MS), with 3 tries in all, the first one included, and the Floor saysreview tries againin between. Then the panel and the relay's log say why, and the PR waits on you until a review of it starts: Needs you gives a line with the reason when the PR is a task's, its Dev's row on the Floor says PR waits on your review andautomatic review could not start,ticket.js floortells the Lead the same, and the Lead gets a saved message asking it to tell you. Fix what the message names and press Get a review, which also ends the wait. So does any other review of the PR that starts, such as a follow-up after a push, and the Lead's saved message goes with it.
A follow-up review that could not start 3 times waits on you the same way.
Turning Review PRs automatically off while a review waits for a desk or its next try drops it. A review that gave up stays waiting on you.
A review frees a desk. Idle Devs whose PRs wait on a review can hold every desk, and then the reviews wait for a desk while the Devs wait for the reviews. So an automatic review, first or follow-up, that waits for a desk frees one by itself. Each second, while every desk is taken, the relay stops one session for the review that has waited longest. It picks, in this order, the one idle the longest of each kind:
- a reviewer whose review is posted;
- a Dev whose PR merged or whose task is Done, with nothing uncommitted or unpushed in its checkout;
- a Dev whose PR is open and waits on a review: a review of it waits to start, or a reviewer of it runs and has not posted. Bring back returns it to the same checkout, and news of its review waits for it, as for any Dev whose session ended.
It stops only a session the Floor calls safe to stop (the same verdict), so never the Lead, a session in a turn or waiting on you, a session with text typed in its prompt, or one with a job running. It stops one at a time, and waits up to 10 seconds for a session that is ending before it stops another. This is not the Lead's stop: Let the Lead stop sessions and the Lead's hourly limit do not apply, and it is not only Autopilot's own sessions. The panel and the relay's log say The relay stopped Eli (Dev, task 3758c1) to free a desk for the review of PR #2: its PR waits on a review, idle 41 min, and Bring back returns it to the same checkout. The chat says it too, and so does the task's history. For a task Autopilot started, its PR's line in Autopilot and Autopilot's notes say it as well.
When it may stop none of them, the panel says No desk is free for the review of PR #N, and the relay may stop no session for it. Stop one yourself. once, and Needs you names the wait. It goes on looking each second, and stops one as soon as one may be stopped, such as when a Dev's turn ends. freeForReview in relay/floor.js stops it, and forReview in relay/stop-verdict.js picks it.
The Dev is told when a review starts. Each review of a PR that starts, the first one, a follow-up or one from Get a review, is told to the PR's Dev as a saved message: A review of your PR <link> started. Ada is reviewing commit <commit>. You need not do anything now. Its findings come as a comment on the PR. The commit is the one the reviewer's checkout is at. The name is the one the relay gave the reviewer as it started it, with no page open too. A reviewer with no name, as when the relay found no roster, is A reviewer. The Dev is the session whose task has that PR, or that opened it. With none, nobody is told and the relay's log says so. A start that is not typed yet is replaced by a newer start of the same PR, and is dropped after an hour. The Dev's desk on the Floor shows it too: see the status icon.
Reviewers leave once they have posted
A reviewer that relay/checkouts.js started for a PR gives its desk back by itself. The relay waits for two hook events from it: a PostToolUse that says a gh pr comment or gh pr review to that PR worked, and then Stop. It then waits RELAY_REVIEW_GRACE_MS, about 30 seconds, and stops the session. Its checkout goes if nothing is left in it. Otherwise it waits for Clean up, and the panel says what is in it. The panel also says who finished, with a link to the comment, or to the PR after gh pr review, until you press OK, and GET /terminals lists them as finished. reviewDone in relay/terminal.js is the one place this ending happens.
- Typing into its terminal, or a prompt from you, during those 30 seconds keeps it until you stop it, or until it posts again and that turn ends. Answers xterm sends by itself, such as focus, cursor and mouse reports, do not count.
- Once it has posted, the relay types nothing into it: a huddle does not ask it, and messages wait. A prompt the relay typed before that, such as the review prompt, does not count as yours. Nor does a task notice, the prompt Claude Code types when the reviewer's own background command ends: it only waits for the next
Stop. - Its verdict is linked to the post as the hook reports it, so a reviewer you keep still counts toward Autopilot. Typing into it does not hold a merge: a merge verdict it posted can merge while you talk to it. A new verdict it gives counts only once it posts again. To hold the PR, turn Autopilot off. If a turn ends with a verdict kept but no post seen, the relay looks on the PR for it: a comment by the account
ghis signed in as, posted after the review started (or after its verdict, if that came first, less a minute for clocks that differ), whose first line is a heading such as## Review of 99296df..04fe778that names the verdict's commit, alone or at the end of a range. The newest such comment is linked, and the reviewer then leaves as if its post had been seen:RELAY_REVIEW_GRACE_MSafter that turn ends, unless something else was asked of it since. The relay's log saysThe review of … is on the PR. - Only
ghat the start of a command counts. One in a heredoc, in quotes, or afterechodoes not, and nor does--help,--web,--edit-lastor--delete-last. A command the hook cannot read leaves the reviewer running. - The post must say which repo it went to: the comment's link, a PR link,
-R, or what Claude Code reports about the command. A baregh pr review 28with none of these could have gone to another repo's PR 28, so it does not count, and the reviewer stays. Give it-R owner/repoor the PR's link. - A post that failed, a post to another PR, or no post, and it stays.
- If hooks do not reach the relay, it stays. The sign comes only from hooks. Hooks installed from an older copy of
office-hook.jsdo not send it either. gh pr commentcounts only if its output has the comment's link, which it prints when it posts.gh pr reviewprints nothing outside a terminal, so only its exit code says it worked. It counts only when nothing runs after it but more commands joined with&&. After| tail,; echo,|| true,&or another line, a failure would be hidden, so it does not count, and the reviewer stays. This matters because GitHub refuses--approveand--request-changeson your own PR.- Lines joined with
\are read as one command. When one command posts twice, the last post sets the kind. - A post through
gh apidoes not count. - Get a review on a session with a PR starts the same reviewer, so it ends this way too.
- No other session ends this way: not Get a review on a session with no PR, and not a Dev, the PM or the Lead.
Review again after each push
With Review again after each push ticked (it starts unticked, and the relay keeps it), a PR that has had a review gets a follow-up review once its latest commit is not the one its last review read. The relay starts it, so the page need not be open. Each second it compares the latest commit that the pipeline check last heard from GitHub with the commit the last review read. So a push counts even when its hook never reached the relay, for example during a restart: the review comes at most one pipeline check later. A git push hook only makes the relay ask GitHub at once. Any way of writing the push counts, quiet, piped or inside an if, a loop or { } too. A push that sends no commits to a branch does not: --dry-run, --delete, a refspec :branch, which deletes (a bare : still counts), --tags with no branch named, --mirror, and one that printed Everything up-to-date with no line of a branch it moved. A PR the relay never reviewed, a PR whose first review still waits, and a PR that merged or closed get no follow-up. The relay also starts nothing for a PR until it has heard from GitHub after its last review started, so an older answer cannot bring a review of a commit already reviewed. With Check each PR's pipeline every at 0 the relay knows no commits, so only a session's git push brings a follow-up, of the session's PR: its task's PR, or the one the relay saw it open with gh pr create. Before the review starts, the relay fetches the PR and compares its latest commit with the one the last review read (unlessAt on POST /checkouts). If they are the same, for example after a push that failed or sent nothing, no review starts, nothing is counted, and the panel says so. A commit that could not start its review, or that the fetch found unchanged, does not bring another try by itself: the next new commit does, or Get a review.
While Autopilot is on, this runs even when the box is unticked. The follow-up reviews only the commits since the commit the last review read, and for a merge of main only how its conflicts were resolved, with git show --remerge-diff.
It starts once the Dev's turn ends, since it may push again, and not while it waits on you. The Dev is the running session whose task has that PR, or that opened it. With none, the review does not wait for a turn, and its checkout is made from the folder of the PR's earlier reviews, or its task's repo. It also waits for the pipeline on the new commit, as in A clean pipeline before review. It also waits while any review of that PR is running, since that review read an older commit. Several pushes in that time bring one review, of the latest commit. The reviewer posts a PR comment, says for each finding of the earlier review whether the new commits fix it, and then leaves, like the first one.
Each PR gets at most 3 automatic reviews, the first one included, unless you change Automatic reviews per PR in Settings. Reviews the Lead asks for (The Lead starts a review) count toward the same limit. A new commit after that starts nothing, and the PR waits on you: its Dev's row on the Floor says PR waits on your review, ticket.js floor tells the Lead the same, and the Lead gets a saved message asking it to tell you. The next review is yours to start with Get a review, which also ends the wait. Reviews from Get a review are not counted. The relay keeps the counts, the switches, the commit each PR's last review read, and a push still waiting for its review, so a restart or a reload loses none of them. A waiting push keeps its Dev's session id too, so when a restart brings that Dev back at a new desk, its review still waits for the end of that Dev's turn. With no desk free it waits for one, as a first review does (A review frees a desk), and that is not a try. If a review cannot start for another reason, it tries again a minute later (RELAY_REVIEW_RETRY_MS), with 3 tries in all, the first one included, and then the panel says so. A PR reviewed before the relay kept these records has none, so its next push starts no follow-up until it has a review from the relay. office/reviews.js decides which review each button starts, writes their briefs, and decides when a PR owes another review (followUpOwed) and when it starts (followUps). relay/reviews.js starts them.
A clean pipeline before review
Nobody reviews a PR, and nobody is asked to merge one, until its checks pass on its latest commit. relay/pipeline.js asks gh pr view --json state,headRefOid,statusCheckRollup about each open task's PR, each PR whose review waits, and, while follow-up reviews are on, each open PR that has had a review, every 15 seconds (Check each PR's pipeline every in Settings, or RELAY_PIPELINE_POLL_SECONDS). It also asks at once when a PR opens or a push arrives. A pipeline is green when every check passed or was skipped, red as soon as one failed, pending while one is running, and none when the PR has no checks at all.
- The worker's brief says to run
gh pr checks --watchafter opening the PR and after each later push, fix any failure on the branch, and say the work is ready only once every check passes. If gh says no checks were reported, the worker asks again a minute later, and says in the PR if there are still none. - Automatic reviews wait. A new PR's first review, and a follow-up after a push, start only once the pipeline is green. While they wait no reviewer starts, so no desk is used. The panel says PR #N is open. Its review starts once its pipeline passes.
GET /reviewslists the PR withheld, itspipeline, andwhyit waits. A follow-up also waits until GitHub has a newer commit than the one the last review read, so a push that has not reached GitHub yet is not judged by the old commit's checks. It waits for that no longer than the no-checks wait below. After that the old commit's checks decide, and if GitHub still has that commit, no review starts, as for a push that sent nothing in Review again after each push. - A wait ends early when the PR merges or closes: no review starts, and the panel says No review of PR #N: It was merged before its review started. It also ends when you press Get a review on its session while the first review waits. That review is the PR's first, and the automatic one does not start too.
- A red pipeline starts no reviewer. The Dev gets a saved message once for each failed commit, telling them to run
gh pr checks, fix it and push, and the panel says so. If the Dev's session has ended, the panel says that nobody could be told. When a later push turns the pipeline green, the review starts then. - No checks configured. GitHub can take a moment to start a PR's checks, and gh reports no checks the same way in that moment. So a PR with none waits 2 minutes (Review a PR with no checks after, or
RELAY_PIPELINE_NO_CHECKS_MS), counted from when this commit was first seen with none. If none have appeared by then, the repo has no pipeline, the review starts, and the panel says It has no checks, so the review starts with no pipeline. When gh cannot read the checks at all, for example when it is not installed, the review starts after the same wait, and the panel says why. - The Board. A task in In review or Waiting on you whose pipeline is pending or red is not ready for either. Its card stays in the Building column, unless Needs you names it for another reason, with waiting on the pipeline: checks are running or a check failed, and so does its note on the wall board. The Tasks panel keeps the state you set, and says Waiting on the pipeline, not on a review (or not on you). Once the pipeline is green the card goes to the column its state names. Other cards show pipeline failed, pipeline running or no pipeline next to their other details.
GET /tasksgives each task apipelinewith itsstateandwaits. The Lead'sticket.js tasksdoes not: the Lead reads PRs with gh. A huddle says a task set to Waiting on you waits on the pipeline while it is running or failing. - With Check each PR's pipeline every at 0, the relay asks nothing, reviews start without waiting, and the Board shows no pipeline.
A red main
Two PRs that each pass CI can break main when they merge minutes apart, since neither was tested with the other. So CI runs on each push to main, as it does on each PR, and the room shows when main is red. Main here means the base branch of a task or ticket, which is main for most.
relay/main-ci.js asks gh run list --branch main --event push every 2 minutes (Check main's CI every in Settings, or RELAY_MAIN_CI_POLL_SECONDS). It asks once for each repo and base branch that a task in the room uses, and for the repo of the ticket Autopilot is about to start. It asks about one branch again only once its last answer is that old, so it adds one GitHub call a branch each time, fewer than the pipeline check makes for one PR. For each workflow it takes the newest finished run that a push started and that was not cancelled. The weekly run and a run you start by hand also test Node 18, so they do not count: a failure there does not make main red, and a pass there does not clear it. Main is red when one of those push runs failed, timed out or could not start. A run still going changes nothing, so main stays red until a push run passes.
While main is red:
- Needs you shows one line for it, with the failed run's link (Needs you).
- The Lead's Floor.
ticket.js floorprints a line above the sessions:Red: main of Building58: CI at 1a2b3c4 ended in failure.and the link.GET /floorgives it asmainRed. - Autopilot starts no new ticket on that base branch of that repo. A ticket on another base branch still starts. Its idle line says
Main is red, so T-5 waits:and the same words. Work already started goes on: reviews, fixes and merges are not held. Fixing main is work for a person or a ticket.
When a push run on main passes, the line clears at the next check, and Autopilot starts work again. While gh cannot answer, main is not shown as red and nothing waits for it. With Check main's CI every at 0, the relay asks nothing and shows no red main.
Getting a review by hand
Get a review shows while a session is on screen. If the session has a PR, it starts the same review as the automatic one. A session has a PR when its task has one, when this page saw it run gh pr create, or when its PR waits on your review. This page knows the PR by the session's id, from a hook it heard, whether or not the session had a desk then. Nothing else keeps that PR, so a reload of the page forgets it, for an Add worker session or a session with no desk. A task keeps its PR. Then it starts a worker in their own copy of the PR's latest commit, who posts a PR comment without asking first and then leaves, like an automatic reviewer. So push before you press it, because work that is not pushed is not reviewed. They are asked for a verdict too, with the same words, so a review that finds nothing blocking counts for Autopilot. This review is not counted toward Automatic reviews per PR: only the reviews the relay starts are. For any other session, it starts a worker in that same folder, since they have to see its uncommitted work, and they report in their own terminal. The page sends their brief with the start, and the relay types it once their session shows its prompt, however long Claude Code takes to start (see a first prompt).
How findings get back to the Dev
Three kinds of finding. The verdict ask in each review of a PR tells the reviewer to mark each finding with one kind (relay/autopilot.js):
- Blocking: a bug, or something that does not do what the PR says.
- Fix now: small and safe to fix in this PR, such as a wording fix, a missing test case, a named const or a doc line.
- Follow-up: real work outside this PR.
A review with any blocking or fix-now finding gives the verdict fix, so the Dev fixes those findings in the same PR and pushes, and the follow-up review checks them. That review counts toward the same limit of automatic reviews as any other. A review gives the verdict merge only when every finding is follow-up, or there are none. The Dev files a ticket for a follow-up finding only when it is a real bug or risk outside the PR. Polish not worth a ticket gets a reply on the PR and is dropped. When a follow-up review reads only the new commits, a new finding there is blocking only if it is a bug in them, and fix now only if it is in them. A blocking or fix-now finding they do not fix keeps its kind.
The relay checks the PR of every task that has one and is not Done, and of every session with no task that opened one, about once a minute (RELAY_REVIEW_POLL_SECONDS), and at once when an automatic review of that PR is posted with its verdict, with gh api: comments, reviews and inline comments, from reviewers, from you, and from sessions it did not start. It does not ask gh when the page polls, so the Tasks panel's 2-second refresh is unchanged. What it has seen is saved on the task in tasks.json, so a restart neither loses nor repeats a comment. If news arrives while a message is being typed, the next message can repeat the links of the one before. Edits to old comments are not news. relay/pr-comments.js does this. Its tell() takes any news for a task's Dev. So the Lead does not carry reviews to a Dev, which would tell the Dev twice. Its brief says Devs get PR reviews from the relay, and asks it to check that they act on them. Only one check of a PR runs at a time, so the Dev is never told the same comment twice. A check asked for while one runs waits for it to end, then runs again, since the one under way may have begun before the review it was asked for.
- The first check. The relay notes when it started watching a PR: when the Dev's hook gave the task its PR, or, for a PR recorded before this, its first check. Comments made more than a minute before then go to the Dev once, in one message that says they may be dealt with already. Telling the Dev about them moves no card, since a person or the Lead may have handled them. The minute is there because GitHub gives times in whole seconds on its own clock, and the relay notes the start on this computer's clock: a comment in the same second as the hook, or one from a GitHub clock a few seconds behind this one, is new. A comment with no time on it counts as new.
- What is news. Everything except: a comment whose link the Dev's own session reported in a hook (a
gh pr commentthat worked), a comment that starts with<!-- office:dev -->, the relay's own note (it starts with<!-- office:told-dev -->), the Lead's Ready to merge note (it starts with<!-- office:ready -->), the summary that the Exhibit GitHub Action posts and updates on each PR (it starts with<!-- exhibit:pr-summary -->and has no findings; other comments fromgithub-actions[bot]are news, since an Action can post real findings), a draft review, and a review with no words of its own, whose inline comments count on their own. All sessions post as the same GitHub account, so the author cannot tell them apart. If the Dev replies withgh pr revieworgh apiand forgets the mark, or the relay misses its hook, the Dev is told about its own comment. That is the safe side: a mistake tells the Dev too much, never too little. - Telling the Dev. The news is saved on the task, then typed as a saved message (
relay/delivery.js), so only when the Dev's session is idle. A message never goes in while the Dev is working or waiting on you, since typing then could answer a question, and the task says Review waiting until the Dev is idle. The message has the PR, a count and up to 5 links, never a comment's words. It asks the Dev to read each one, fix or dispute each finding, reply on the PR starting with<!-- office:dev -->, and push. It fixes each blocking and fix-now finding in this PR. A finding marked follow-up needs no push: the Dev files a ticket for it only if it is a real bug or risk outside the PR, and otherwise only replies. When every comment in the news is a review posted with a merge verdict and no review on GitHub requested changes (the same test as for the card, below), the message says not to push for its findings, since each push makes the review stale and brings another round. Instead the Dev replies on the PR, files a ticket only for a finding that is a real bug or risk outside the PR, naming the PR and the finding (ticket.js createwith a quoted heredoc), and stops. Polish not worth a ticket gets only the reply. If the Dev thinks a finding marked follow-up is really a bug in this PR, it says so in a new reply with<!-- office:hold -->on the line after<!-- office:dev -->, and pushes no fix. The relay reads the mark only the first time it sees a comment, so a mark added to an edited reply does not count. When the relay's comment check sees that reply, the task's history says so, and a task Autopilot started goes to Waiting on you instead of merging. Autopilot also checks the PR's comments once more just before each merge, so a reply posted since the last check still counts. That check needs Check PRs for comments every above 0. A failing check and a conflict with main are still the Dev's: it fixes the check, or merges main, and pushes only that. The Dev's brief says the same. Which message the Dev gets is chosen once, when the news is queued, and the card follows that same choice. News that arrives before the Dev is told joins the same message. A link already waiting is not added again, so the count is the number of links waiting. - After it is typed. The task moves back to Changes requested, signed
relay, from any state but Done. It stays where it is when the message was the merge one: every comment in the news is a review posted with a merge verdict (ticket.js verdict) and no review on GitHub requested changes, since such a review blocks nothing. The task's history says so. It also stays in Waiting on you while Autopilot has handed the task to you and you have not moved its card since, so the column still says a decision waits on you. The Dev is told all the same, and the task's history says why the card stayed. A verdict counts only for the review it was posted with, never for a later comment. A review posted withgh pr commentis matched by its link. One posted withgh pr review, which prints no link, is matched to a review or inline comment on GitHub from within 15 minutes after the verdict. It counts from the moment the reviewer posts, not only once its session has ended. So a comment with no verdict of its own, as from a person, or a review whose reviewer gave no verdict, moves it. It moves even at the WIP limit, since its worker is already running. A task the relay moved back from a column that does not count, such as In review, does not count againstRELAY_WIP_LIMITuntil its next move, by anyone, so it never makes Start or Bring back be refused. See the limit. The relay posts a note on the PR saying the Dev was told, and the task's history and the Tasks panel say so. If gh fails to post it, the relay tries again at the next check. - A Dev whose session has ended. The news waits on the task, and the Tasks panel says Review waiting, Dev session has ended. Press Bring back, and it goes in once the Dev is idle. That holds when Bring back starts the Dev over with a new session, because its brief never went in: the news goes to the new session. The relay does not move the task to Waiting on you, because that moves its card past Building, which
docs/constitution.mdarticle 1 leaves to a person. - gh failing. If gh is missing, not signed in or failing, the task, the panel and the relay's log say so, and it tries again on the next check. A failed check is never read as no comments.
- A task that is Done is not checked, and news still waiting for it is dropped, with a line in its history. A note on the PR still owed is posted once when the task is Done. If gh fails then, the note is dropped, with a line in its history.
- A session with no task. A session from Add worker has no task to keep what the relay has seen. When its hook says it ran
gh pr create, the relay watches that PR for it, and keeps what it has seen insession-prs.jsonin its state folder, so a restart neither loses nor repeats a comment. A session watches one PR: a secondgh pr createfrom it of another PR replaces the first, and one of the same PR, as whenghsays the PR already exists, keeps the watch and what it has seen, even after the session's id changed with/clear. The PM, the COO, Security, the Lead, reviewers and game seats are not watched. The session is told the same way as a task's Dev, with the same message, and the PR gets the same note, with three differences. There is no card, so nothing moves. The ticket chat is not told. And a reply with<!-- office:hold -->holds no merge, and no push hold is set, since Autopilot does not merge such a PR. The watch ends when the session is stopped, by you or by anyone else, or when the relay asksgh apiabout the PR and it is merged or closed. A session that ends by itself keeps its watch, and news waits for it until it comes back with the same id. The relay's log says when it starts and stops watching such a PR, and each time it tells the session.
The push hold
After a review's verdict says merge, a push for its findings costs a pipeline run and a review round, and can break what was reviewed. So the Dev's checkout refuses such a push. relay/push-hold.js does this.
- The mark. While the latest posted verdict on a task's PR says merge, the relay writes
office-push-hold.jsonin the git folder of the task's checkout (its folder under.git/worktrees, so git never shows or commits it). It holds the PR, the reviewed commit and the task's base. The relay checks it when a verdict is posted, when the task changes state or gets its PR, when the relay starts, and on each of Autopilot's looks while Autopilot is on. - The check.
.githooks/pre-pushdoes nothing when there is no mark. With a mark, a push goes through only when each new commit since the reviewed one is a merge whose first parent is the reviewed commit or another such merge. A merge oforigin/mainthat GitHub needs to clear a conflict passes. Any other commit, a merge of another branch, or the deletion of the branch is refused with: The review of <commit> says merge. Do not push. Reply on the PR, and file a ticket only for a finding that is a real bug or risk outside this PR. - A stale verdict. When the PR's branch already has commits the verdict did not read, as when the Dev pushed while the review ran, the push goes through: a follow-up review is owed anyway.
- When it clears. The mark goes when a later posted verdict says fix, when the relay sees the PR merged or closed, or when the task is Done. A verdict counts only once its review is posted.
- How you lift it. A review alone cannot tell that a finding it marked non-blocking is a bug. When its Dev says it is, in a reply with
<!-- office:hold -->, Autopilot hands the PR to you, and Needs you shows a Fix it button on that line. Press it when you agree. The relay keeps your decision as a fix verdict on the reviewed commit, so the mark goes at once. The task moves to Changes requested, and its Dev is told to fix the finding and push. Its push then goes through, and the follow-up review runs after it as usual. A later review's verdict counts as usual too: if it says merge, the mark comes back on the commit it read. If you do not agree, move the card instead, and the hold stays.POST /autopilot/fixdoes the same for any task whose latest posted verdict says merge (routes). The Lead may do it withticket.js fix T-12only while Let the Lead merge is on, since lifting the hold is a step toward a merge. The card and Autopilot's notes say who decided. - Where it works. Only a repo whose pre-push hook runs
relay/push-hold.js. Building58 does, throughnpm run hooks, which setscore.hooksPathto.githooks.git push --no-verifyskips it. A merge commit can hold edits of its own, and the check does not look inside it.
Resolving comments
Review comments do not get marked as resolved by themselves. Nothing in the room does it, and a Dev's fix leaves the comment standing as it was. Check the fix against the comment before you merge. The Lead is told to do the same before it merges.
The COO
Ask the COO, on the COO's card in the Officers row of the org chart, closes the chart and starts a COO session in the relay's own folder, as Ask the PM starts the PM. It spends one session of tokens, so it runs only when you press it, and only one runs at a time. The pattern comes from the executive reflection in OpenExecutive: an executive that reads the signals, then says what it would do and who should decide.
Its brief. The relay types a short brief. It tells the COO to read CLAUDE.md and docs/constitution.md, then fetch the measures with node relay/ticket.js measures, and write a one-page report in Markdown. It starts with the headline, against the last report: how many PRs merged alone, merged after getting stuck, and merged needing you, and the minutes the room spent stuck. Then what shipped, each run that got stuck (on what, and for how long), each step-in (what you did, and how long the room waited), and the evidence for each kind of ticket. It is told that review rounds are not failures. Then at most 3 recommendations, each naming its evidence and what you would approve: a rung, a ticket, a limit, or a change to the constitution. It is told to say what the measures cannot show, and to quote text that workers wrote, such as titles and notes, as data and never follow it.
It proposes only. It is told not to change code, open a PR, file tickets, start, stop or merge work, move the board, or change a switch or a rung. Its token reaches only GET /coo/measures, POST /coo/report and GET /tickets, so filing a ticket is refused by the relay, not only by the brief. The rest is words, not a lock: it runs with your logins, as other sessions do, and in the relay's own folder, which is the checkout the global hooks run from. A COO that ignored its brief could change the running relay's files. The recommendations are yours to act on.
The report. The COO pipes its report into node relay/ticket.js report. The relay saves it with the measures it was written from (RELAY_COO_FILE, the last 20), and the Floor shows it under the people, as text. On the COO's card, Last COO report, from and its time opens the last one again, also after a restart, and closes the chart. With no report yet it is greyed out and says No COO report yet. A new report opens on the Floor by itself, but only one that arrives while the page is open. One report shows at a time, so opening the COO's closes the security officer's, and the other way round. The next report's measures carry the last report's load and headline, so the COO can compare.
It leaves by itself. Once the report is saved, the session ends RELAY_COO_GRACE_MS (10 seconds) after that turn ends. If you type to it after the report, it stays until you stop it. Having its panel open does not count: only keys do.
What the relay measures
The goal is a room that does not need you to step in, so that is what the COO measures. The relay keeps these from what it already sees: the tasks and their history, the Board, the PR watcher, hooks, Autopilot and Update. relay/coo.js works them out each time they are asked for.
- Shipped. A task ships when its PR merges, whatever its card says. A PR that merged while its card stayed in Building or Waiting on you counts. The merge time is GitHub's, which the relay keeps in the task's history when
gh pr viewsays the PR merged (How the relay hears about PRs), or the time Autopilot saw its own merge. A task in Done with a PR from before the relay kept merge times merged when it moved to Done. - Each run's outcome. A run is a task, from its start until its PR merged.
- Success: merged, and you never stepped in. Review rounds do not change this: a Dev that fixed what a review found is the room working as it should.
- Needed you (
manual): merged, but you stepped in. A step-in is a raised hand, Waiting on you (from Autopilot too, unless Autopilot brought the task back by itself because its stuck session moved again, or because something moved it after a stall), Get a review that you pressed, a session you stopped on its panel, or Bring back that you pressed. Each says what it was and how long the room waited. A Bring back by the relay after a restart, or a stop by the Lead, is not yours. - Stuck: Autopilot or a session got stuck, and the room waited. That is Autopilot sending the task to Waiting on you (it was stuck for the time in
RELAY_AUTOPILOT_STALL_MS), a brief that never went in, a Dev or reviewer that did not start on what the relay typed into it, a session in a turn that was stuck with no hook and no output forRELAY_STALL_MS(30 minutes), counted from its last hook, or a session that crashed. Each says on what, and for how long: until the next move, the brief, the session working again, or the merge. A stuck run is stuck even if it merged later. - Open: still going, and not stuck. Closed: in Done with no PR that merged.
- The headline, since the last report: PRs merged alone (success), PRs merged after getting stuck with no step-in by you, PRs merged that needed you, and the minutes the room spent stuck. The three counts add up to the PRs merged. Where stuck times overlap on one run, they count once.
- Your load. Each raised hand: a session waiting on you, from the hook that said so until it worked again, went idle or ended, and each task in Waiting on you, until its next move. Hands per day, since the last report, the median and longest wait, and the last 10.
- Flow. How many tasks merged, are open, or are closed, the median time from start to merged, median time from filed to started, the minutes tasks spent in each state, and how many tickets wait in Triage and Ready.
- Quality, as information. For each PR, the comments the PR watcher saw that were not the Dev's or the relay's, how many were reviews that requested changes, and how often the task went back to Changes requested, and by whom. None of these is a failure. These are comments, not findings: a review with seven findings is one comment, and a Lead's note is one too. The watcher counts from the first check after this change, and each PR says since when. A PR it had not checked since then shows no count. The relay does not see CI, so work sent back by CI is not counted.
- Recovery. Stalls, with how each ended: a session in a turn that sent no hook and, for the stall time, printed nothing (
RELAY_STALL_MS), from its last hook, a brief that never went in, and a session that did not start on what it was told. A relay stop that ends a session records no stall. Quiet spells, listed apart and not counted as stuck: a session in a turn with no hook for the stall time while its screen kept moving, with how each ended. The relay looks at each session every second for these. Crashes: a session that ended with an error code that nobody stopped, and whether its task was brought back. Updates that failed to pull or whose restart was called off. The relay has no rollback, so there are none to count. - Cost. Time per ticket, to its merge, and its review rounds. Claude Code's hooks do not report tokens, so there are none.
- Rung evidence. Each run's outcome by kind of ticket: the kind set on its ticket. A ticket with none gets a guess from its title (docs, tests, bug or feature), and
guessedcounts those, on each kind and on each ticket.
The security officer
Ask security, on the security card in the Officers row of the org chart, closes the chart and starts a security session in the relay's own folder, as Ask the COO starts the COO. It spends one session of tokens, so it runs only when you press it, and only one runs at a time. The role comes from the general counsel in OpenExecutive, which has no security officer: it frames the risk and says when to escalate, and it does not decide. While it runs, its card in the Officers row says it is in, and who sits there.
Its brief. The relay types a short brief. It tells the session to read CLAUDE.md and article 7 of docs/constitution.md, then fetch the measures with node relay/ticket.js access, and write a one-page report in Markdown: the logins sessions inherit, the folders they reach, what the relay takes out of their environment, and what the secret check caught, against article 7, which rungs 3 and 4 wait for. Then at most 3 recommendations, each a ticket, a limit or a change to the constitution for you to approve, with its evidence. It is told to say what the measures cannot show, and to give names only: never to print or copy the value of a variable, a token or a key file.
It proposes only. It is told not to change code or anyone's access, open a PR, file tickets, start, stop or merge work, or change a switch. Its token reaches only GET /security/measures, POST /security/report and GET /tickets, so filing a ticket or reading the chat board is refused by the relay. The rest is words, not a lock: it runs with your logins, as other sessions do, in the relay's own folder. Each change to a session's access is its own ticket.
The report. The session pipes its report into node relay/ticket.js access-report. The relay refuses a report that the secret check says holds a key, or that holds the relay's key, a session's token, or the value of a variable the measures name as looking like a login. The secret check's secret-check: allow marker does not count in a report. The refusal says which line and what kind, never the value. A secret that matches none of the check's patterns and is not a value the relay holds, such as a .netrc password, is not caught: the brief, which says never to copy a value, is the only guard there. A saved report is kept with the measures it was written from (RELAY_SECURITY_FILE, the last 20), and the Floor shows it under the people, as text. On the security card, Last Security report, from and its time opens the last one again, also after a restart, and closes the chart. With no report yet it is greyed out and says No Security report yet. The next measures carry the gaps the last report saw.
It leaves by itself. Once the report is saved, the session ends RELAY_SECURITY_GRACE_MS (10 seconds) after that turn ends. If you type to it after the report, it stays until you stop it.
What the relay reports on access
relay/access.js works these out each time they are asked for. Every one is a name, a path, a count or a yes or no, never a value.
- The environment. A session gets the relay's environment, which is yours, built by
relay/session-env.js, the same code that starts each session. The measures list the names it passes on, the names it takes out (the relay's settings, and the variables of a Claude Code session that started the relay), and the names it adds (the session's desk, channel, ticket token and hook address). Names that look like a login, such asGH_TOKENor one withSECRETin it, are listed again apart. That is a guess from the name. The relay takes its own key out of its environment as it starts, so the key is not there to pass on or to remove. - Logins in your home folder that every session can use:
gh(its hosts), git credentials,ssh(the names of its keys),aws(its profiles),gcloud,npm(whether it holds a token),.netrcanddocker. Each says whether it was found. No secret is read into the measures. - Folders. Where each running session works: its own checkout, the relay's own folder, or another folder. Your Claude Code permission settings in
~/.claude/settings.json: the default mode, and how many allow, ask and deny rules and extra folders there are, not their words, since a rule can hold a command with a key in it. The relay passes no permission flag, and the operating system lets a session reach every file your user can, so those settings are the only fence. - Rungs. Which Lead may merge, start tickets or move the board.
- The secret check. Whether its pre-commit hook is on in the relay's folder (
git config core.hooksPathis.githooks), and what it finds in the tracked files now, as file, line and kind. The relay does not see what the hook stopped before a commit, so that is not counted. - Gaps. Each place where the above is short of article 7, and which rung waits on it: login variables and login files every session inherits, a Lead that merges with your full GitHub login, a Lead that starts tickets, a session in the relay's own folder or outside a checkout of its own, the hook off, a secret in the tracked files, and Claude Code set to ask nothing.
- What it cannot show. Logins in the macOS keychain or another credential store, what each login may do on its service, what a session read or ran, each checkout's own
.claudesettings, and a secret in a report that the report check does not catch, as above.
Huddles
Status report, in the bar at the top of the Floor, gives one short report with a line for each running session and each unfinished task with no session. Each line has who they are, the ticket and PR, working, waiting on you, finished or gone, the pipeline and review, what they are waiting on, and how long since a hook last heard from them. What needs you comes first: a line that Needs you names shows that list's line, and the headline counts that list, so the two agree. Everything else, such as a failing pipeline nobody is on, shows only in what the line waits on. The report shows on the Floor under the people until you close it. A report made before the page loaded does not open by itself. A line above the buttons says what a huddle is, and its ? opens this section.
The report reads what the relay, git status and gh pr view already know. It interrupts nobody and spends no tokens. If gh fails the report says so, and shows the PR as unknown, not as missing. The relay's side is relay/huddles.js, and the page's is office/huddle.js.
- Ask idle workers too spends tokens. It is a separate button, because each answer is a turn. It says how many it would ask, as Ask idle workers too (2, one turn each), and with nobody to ask it is greyed out and says nobody is idle. It types a one-line question into each worker that has finished a turn: Devs, reviewers and other sessions, never the Lead. Each answer comes into the report you see. It does not ask the Lead, or a session that is working, waiting on you or has not started, or one with text typed in its prompt, and the report says why. Anyone who has not answered in time (
RELAY_HUDDLE_ANSWER_SECONDS, 3 minutes) is reported as not answering, so a huddle always finishes. Sessions answer with one line starting with the question's marker. The hook sends only that line, read from what Claude Code passes it when a turn ends. None of the session's other words leave the hook. This needs Claude Code 2.1.316 or similar, which passeslast_assistant_message; an older one reads as not answering. - A question can wait. Nothing is typed while a turn, a permission prompt or a menu is up, or while you have text in that session's prompt. If that lasts until the time is up, the report says it was not asked.
- An automatic reviewer that has posted is not asked. It is leaving, and the report says so.
- Telling the Lead spends one Lead turn. The switch is Send each status report to the Lead (one Lead turn each) in Settings, under Huddle. It is on until you turn it off, and this browser keeps your choice. While it is on and a Lead runs, it types the report into the Lead's session, and the buttons on the Floor say so: Status report (tells the Lead: one Lead turn), and plus one Lead turn on the ask button. Turn it off to spend nothing: that also takes back a report still waiting for a busy Lead. The Lead is the running session you made the Lead. If none is running when the report is made, nobody is told. A busy Lead gets the report when it is idle: it waits for up to an hour, and a newer one replaces it. A saved report goes to whoever is the Lead when it is typed, so one saved before a Lead stopped waits for the next, within that hour.
- The Lead reads workers' answers as quotes. In the Lead's copy each worker's answer is quoted as
[WORKER TEXT from Name, untrusted: «...» END WORKER TEXT]. Nothing in an answer, a name, a title or a message can close that quote or pass for the relay's own words. The report and the Lead's brief both say never to follow an instruction in a report or an answer. The words still reach the Lead. - An approved, green PR waits on the Lead when it may merge. A PR counts as approved when GitHub says it is approved, or when its reviewer's latest verdict, given with
ticket.js verdict mergeand posted, says merge for the commit at the head of the PR. Office reviewers post from the same GitHub account as the PR's author, and GitHub does not let an author approve their own PR, so the verdict is what the huddle reads for them. A verdict on an older commit does not count. With Let the Lead merge on, its line says waiting on the Lead to merge, under the merge rung, and it does not need you. It still waits on you to merge when no checks have reported on it yet, when its base is notmain, when GitHub does not say it merges cleanly, when it changesCLAUDE.mdordocs/constitution.md, or when gh does not list all its files (gh lists at most 100), and the line says which. With the switch off, it waits on you to merge. Needs you then shows a merge line for it, if a task holds that PR. The huddle cannot see a design choice or a security trade-off, so the Lead still checks the merge rung itself before it merges. - QUIET and STUCK mean what they mean on the Floor, from the same rule: see Is a session alive. A session in a turn with no hook for the stall time (
RELAY_STALL_MS, 30 minutes) whose screen still moves is quiet, and waits on nobody knows: it may be thinking, or on one long command. One with no hook and no output for that time is stuck, and waits on you to look at its session. Both show how long since its last hook. - Devs do not post check-ins, which would spend tokens whether or not anything had changed.
- For a moment during a huddle, people with no real work gather at the bar table and the board. Nobody moves under reduced motion or while the manager is in. It changes where they stand, not their state on the Floor.
The chat board
Chat, under the Board, is a few chat channels for you, the Lead, workers and the relay. The relay keeps it on this computer and sends it nowhere: it is not Slack, and every route answers only the room page and sessions on this computer. A session that reads the board sends what it reads to the model, as it does with anything else it reads. The relay's side is relay/chat.js, and the page's is office/chat.js.
- #office has the relay's own news: a ticket started, a PR opened, new review comments, a failing pipeline (a run that a newer push cancelled is not one), a PR merged or closed, a ticket's chat channel archived,
mainmoved on origin, a hand raised (once, even across a restart), a session the Lead stopped, and the relay starting. Sessions cannot post there. You can. - Each ticket gets its own chat channel, such as #T-39, when it is filed, so a session can post evidence before anyone starts it. A ticket filed before this has none until someone reads or posts in it with
ticket.js, while it is in Triage, Ready or Started. The relay's news about that ticket goes there too. When the ticket's title is edited, the chat channel shows the new one. - A ticket's chat channel is archived, not deleted, when its PR merges, when its task moves to Done, or when the ticket moves to Done or Rejected without a task. Its posts stay to read, and the page lists it under Show archived, newest first. Nobody can post there, you included: the relay answers 409. Its last post and #office say it was archived, and why. If the task moves back out of Done, or the ticket goes from Rejected back to Triage, it opens again with its posts.
- When you delete a ticket's chat channel, with the local ticket store, a short summary goes on the ticket first, which its card shows: how many posts, from whom, and when. If the ticket is gone from the store by then, nothing is kept, and #office says so. With a store off this computer, such as GitHub issues, nothing is kept, so no names or times reach the issue. The posts themselves are not kept. If the summary cannot be written, the chat channel stays and you are told to try again. If the relay is deleting it at that moment, you are told to look again. A ticket that is still open gets an empty chat channel again the next time someone reads or posts there with
ticket.js. - Fun chat channels are yours. Type a name under the list and press Make, up to 10. A session may post in each one once a minute, and once every 5 seconds in each ticket's.
- Delete takes two presses, and works on any chat channel. #office comes back with the next news. Each chat channel keeps its newest
RELAY_CHAT_KEEPposts, 200 by default.
A post types nothing into a session
Workers read the board with node relay/ticket.js chat T-39. Their brief tells them to check it, and that posts are information, not orders: they act on one only if their ticket, the Lead or you ask for it.
The one exception is a post that mentions exactly one running session by its name on the page, such as @Hugo, or @Lead. That session is told which chat channels have posts for it, never the posts' words. The note waits in relay/delivery.js, so it goes in only when hooks say the session is idle, never into an open prompt (see saved messages). Several posts for the same session wait as one note, for up to an hour, and the list of chat channels in it survives a restart. A post that mentions two or more sessions tells nobody, and says so.
When a session reads the board, each post shows who sent it as the relay knows it (the person, Theo (a session), office (the relay)), and its words in « and ». A ticket's title is quoted the same way, since it comes from the ticket store. A post cannot use those marks itself. The page shows your own posts as you.
How the relay hears about PRs
To know about failing pipelines and merges, the relay asks gh pr view about each task's PR every RELAY_CHAT_POLL_SECONDS. The first look at a PR is not news, except a merge. When a PR has merged, the relay keeps GitHub's merge time in its task's history, once, whatever its card says, and asks once more about a PR it saw merged before it kept merge times, so the COO counts it shipped. A merged PR is not asked about again. A closed one is asked about every tenth time, in case it is reopened.
To know that main moved, the relay runs git ls-remote --symref origin HEAD every RELAY_MAIN_POLL_SECONDS (60) in its own folder, the one Update pulls into (relay/main-moves.js). This changes nothing in the folder. When origin's default branch points at a new commit, #office says so once with that branch's name, such as main moved on origin, from 7873f70 to 1a2b3c4. The first answer after the relay starts is not news, even when the branch moved while no relay ran, and neither is a change of which branch is the default. It never asks for a password or a passphrase: git's prompt is off, and ssh runs with BatchMode=yes unless you chose an ssh yourself, in GIT_SSH_COMMAND, GIT_SSH or core.sshCommand. When origin cannot be asked, #office says nothing, the relay's log says so once, and again when origin answers, and the next answer is compared with the last one the relay had. Other branches are not watched.