Sessions and resume

Every conversation is a session: an append-only record of each prompt, each model reply and each tool call. Sessions are stored in the workspace's state directory, <workspace>/.orrery by default (--state-dir <path> moves it).

#Come back to one

Both work with run -p too, so a script can add a turn to an existing session:

orrery --resume 01a0df68 run -p "Now write the tests"

A run that the last process was cut off in carries on at once. A tool call that was mid-flight is answered interrupted; it is never run twice. Sub-agents are not restarted: the thread says which were interrupted, and the model asks again for what it still needs.

A session already open in another live orrery is refused, naming that process.

#List and inspect

orrery session list              # id, turns, profile, workspace
orrery session show <id>         # one session's thread
orrery session show <id> --agent dir-finder-1   # a sub-agent's own thread
orrery session rm <id> --yes     # delete one; --yes is required without a terminal

Deleting cannot be undone, so session rm asks first at a terminal.

#Replay

replay re-emits a stored session as events, so any client can draw any past session:

orrery replay <id> --json

#What it cost

Each provider declares what its models cost. The footer, each turn's last line, /cost in the TUI, orrery telemetry and --json's RUN_FINISHED.result.micro_usd all show it. A model nothing prices shows $ —, never a guess. See [prices] to set a price yourself.

#Budgets

The main agent has no limit unless you set one. Stop it with Esc, or set a budget per run:

orrery --max-turns 40 run -p "..."   # model passes per run
orrery --budget 3.5                  # $3.50 per run, priced from real usage

or once in config.toml (the flag wins):

[budget]
maxTurns = 40
maxUsd = 3.5
toolTimeoutMs = 600000   # one tool call's wall clock; 5 minutes by default

A budget stop exits with code 3 and says which limit was reached. A cost cap does nothing on a model with no price. A sub-agent is always capped: 16 turns by default.

#The node keeps sessions running

orrery node up starts one long-running process per machine that holds many sessions. Sessions survive node down, an upgrade or a crash: the next node up lists them as hibernated, and the first attach or message resumes them. See serve and attach.