Codex turns: steering, approvals, goals, and recovery

One thread, one run: start, owner, and steering #

A Codex run in HB Code is one reader task that follows one turn, or a chain of turns, on one Codex thread. Everything in this chapter hangs on that reader: approvals reach it through the turn route, Stop talks to it through a control channel, a goal gives it the next turn, and recovery gives it a new route. The process, the actor, and the turn route are in the app-server chapter. The outbox that decides when a message is sent is in the message delivery chapter.

The owner record is a map in desktop memory with the Codex thread ID as its key. It stops two app sessions that link the same thread from running it at the same time. The same run can claim again without an error. A stale owner is removed when its recorded Codex child is dead. When the record has no pid, it is removed after 45 seconds, and only if the run is no longer active. The guard is released after thread/unload and before the finishers wake the outbox, so the next queued message finds the thread free.

Steering adds a message to the turn that runs now. The desktop sends turn/steer on the runtime pair that owns the active turn. It opens no thread, starts no turn, and claims no owner, because the reader that already runs keeps all three.

Stop and send now needs one more call. A steer that Codex accepted may still wait inside the turn as pending input. The desktop sends turn/detachPendingInputForReplay with the same threadId, expectedTurnId, and clientUserMessageId. The answers detachedForReplay and alreadyDetachedForReplay permit the replay in a new turn. The answer applied means the model already has the message, so no replay starts. The answers recording and staleTarget, and any error, also block the replay.

Who answers an approval #

Codex asks for approval with a JSON-RPC request, and it waits for the response. The actor of that Codex child keeps each open request in a map and must find someone who can show it. A request that nobody can show is declined, because a turn that waits for an answer that cannot come would never end.

• Delivery has two paths. A request for a turn with a live route goes to that turn’s reader, which shows the card in the session. A request with no route is broadcast to observers. Requests from subagent threads take this path, because no reader owns their turns.
• An observer must claim a broadcast request within 30 seconds. The run’s observer first proves that the thread belongs to its root thread, with a limit of 10 seconds for that check. An unclaimed request is declined when the 30 seconds end.
• A request with no supported decision, and a request with no route and no observer, are declined at once.
• Codex can send the same request again after a reconnect. An identical request keeps its place. A different request with the same ID makes the desktop decline that ID and close the card.
• When turn/completed arrives, the actor declines every open request of that turn before the reader sees the completion. Abandoning a turn and shutting the actor down do the same.
• serverRequest/resolved from Codex closes the card as resolved elsewhere. During the initialize handshake no card can exist, so an approval request is declined.

An answer from the desktop window or from a phone takes one path. A phone calls run.chatResolveApproval, and the desktop offers the answer to every live Codex child, most recently used first. Each actor compares the request ID, thread ID, turn ID, and item ID with its map, so exactly one child accepts it. A decision that the request did not offer is refused.

The access level Unrestricted sends approvalPolicy never. If a request still arrives, the reader answers it without a card. It picks the first decision the request offers from acceptForSession, accept, and accept broadly. The other access levels send approvalPolicy on-request.

Goals: many turns in one run #

A goal is state that Codex keeps on a thread: an objective, a status, a token budget, and counters. While the status is active, Codex starts the next turn by itself when a turn ends. The desktop does not start these turns. It finds each one and attaches a reader, and the whole chain stays one chat run with one operation ID.

A goal has the fields objective, status, tokenBudget, tokensUsed, timeUsedSeconds, createdAt, and updatedAt. The status is one of active, paused, blocked, usageLimited, budgetLimited, and complete. The reader follows the chain only while the status is active.

• A goal run starts with thread/goal/set and status active. It sends no turn/start. Codex starts the first turn.
• After each turn the reader sends thread/goal/get. While the goal is active it sends thread/resume with excludeTurns: false and takes the latest turn. A turn counts when its ID is new or when it is still in progress. The reader tries 3 times, 250 ms apart, then reads the goal again.
• A turn that is in progress gets a turn route and is read like any other turn. A turn that already completed is settled from the snapshot in the resume answer.
• Every Codex chat run ends with the same check. A message sent to a thread with an active goal therefore stays one run until the goal leaves the active status. A run that finds no active goal still looks once for a newer turn with thread/resume, and then it ends.
• A steer that arrives between two turns waits. Each new turn wakes the steer lane of the outbox again.
• A goal run unloads its thread with thread/unload at the end. A failed unload there is only logged.

Stop is a ladder of four steps #

Stop marks the run as aborted and then works down a ladder. The order matters for goals: a turn that is interrupted while its goal is still active would be followed by a new turn at once.

Codex answers turn/interrupt when the turn has stopped, and it sends turn/completed with the status interrupted. The reader takes that completion as the end of the turn, and the run ends as cancelled. A run that was aborted between turn/start and the registration of the turn is handled by the run itself: it pauses the goal and abandons the new turn, and it retries both every 250 ms on transport errors.

The five-second rule after an error #

Codex reports a problem inside a turn with an error notification, and the field willRetry says whether Codex goes on. The error alone never ends the turn. The turn ends with turn/completed, and the reader waits for it, but only for 5 seconds.

The reader wakes every 100 ms when no notification arrives. It uses that tick for Stop requests and for the deadline, and a quiet turn is never failed for silence alone. The 75 ms drain exists because Codex can send the last item notifications just after turn/completed. The same 5 seconds apply to a subagent thread: after an error that will not retry, its thread stops counting as active for the child process after 5 seconds.

turn/completed and an error that will not retry are never dropped on a full turn route. They wait in a separate lane in arrival order, and ordinary events for that turn are dropped while one waits.

When the turn route is lost, the desktop asks for the exact turn #

The reader has one signal for a lost connection: its turn route closes while no error is saved. The actor closes every route when it stops, for example when the child’s stdout closes. The desktop then asks Codex what became of the turn, and it asks for that exact turn. A turn cannot move to another process. A new Codex child loads the thread from its saved history and reports a turn that was still in progress as interrupted. The answer is inProgress only when the child that answers still runs the turn.

• Only a lost connection starts a rejoin. Any other failure that is not a final status makes the desktop abandon the turn with turn/interrupt.
• The reader waits up to 1 second for the old client to close. Then it leases a client for the same runtime pair, and the registry starts a new child if the old one is gone.
• The access settings that the old client recorded for the turn move to the new client, and the owner record gets the new pid.
• When the client changed, the observers for subagent approvals and for agent messages are stopped and started again on the new client.
• The rejoin is thread/resume with excludeTurns: false. The desktop takes the turn with the expected ID from the answer. When the answer has no such turn, the run fails and the desktop abandons the turn.

For every answer the desktop first matches the rows on screen to the snapshot of the turn, so the work that Codex saved before the loss stays in the timeline. A turn is rejoined once. When the new route also fails, the run ends with that failure. Between two turns of a goal the reader has no route to lose, so it recovers on transport errors of thread/goal/get and thread/resume instead, at most 2 times in a row.

Child threads, watched threads, rollback #

A Codex agent can spawn subagents, and each subagent is a thread of its own below the root thread. No run of the desktop owns their turns. The desktop lists them, saves where their files are, and follows one live only while a window shows it.

With no watcher nothing follows a subagent thread. Its notifications stay unrouted, and the desktop reads the thread from history when you open it. An approval from a subagent does not need a watch: the observer of the root run claims it, as the approvals section describes.