How orc runs Pi ​
Orc runs only Pi, and it starts Pi itself as pi -p --mode json in the task copy, inside nono run by default or on the host with --sandbox none.
- Orc passes the agent file's model, thinking level and tools, and the run's
sessionsfolder as--session-dir. - Orc writes the prompt to Pi’s standard input, and the prompt asks the agent to print
ORC_COMPLETEon its own line once the work is committed. - The prompt also asks the agent to print
ORC_SPLITon its own line and then a JSON document when the change outgrows the budget. - Pi prints one JSON event per line, and its first line is the
sessionheader with the session id and timestamp. - On that header orc records the session file, named after the timestamp and the id with
.jsonl, soorc shownames it while the step runs. - Orc writes each assistant message to the step's log on its own line, and each command a tool starts on a line opening with
>. The implement step logs toagent.login the run folder, and each fix tofix-<n>.log. - While a tool runs, orc writes
orc: still running <command> (N min)to that log each minute. - Orc stops Pi only after the idle limit passes with no output and no tool running, so a quiet test command is never cut off.
- Orc counts each bash command whose
tool_execution_endevent carriesisError, as a failure of that command. A success, or a failure of another command, starts the count over, and a tool other than bash leaves it as it is. - At 3 failures of one command in a row orc logs
orc: pi failed <command> 3 times in a rowand writesfailing.jsonto the run folder, with the command and the time. The beat opens an attention item for you on it, as The attention queue shows, and Pi carries on. Orc removes the file when the count starts over or Pi ends. - At 6 failures of one command in a row orc logs
orc: stopped pi, it failed <command> 6 times in a row, stops Pi and asks you to continue or stop, as A looping run shows. - Orc counts the step complete only when the session’s final assistant message stopped with
stopand holdsORC_COMPLETEon its own line. - A valid
ORC_SPLITproposal records the run as failed without running checks or opening a PR. - The beat then turns the task into a parent and starts its children.
- When the task has a parent, its children join that parent instead, as A worker split proposal shows.
- Orc also loads its
orc_askextension into Pi with--extensionand addsorc_askto the tools, as A worker question shows. Pi calls it to ask you a question mid-run instead of guessing or failing. - On resume orc passes the recorded session file as
--session, and Pi continues that session instead of starting a new one. - Orc sums the
usageinput and output counts each session message carries into the run's token totals.
packages/run/src/entities/agent/pi-run.ts starts Pi and reads its lines, packages/run/src/entities/agent/pi.ts checks the final reply, and packages/run/src/features/running-a-task/run-loop.ts reads the session after each step.