Durability
What happens when a run is killed halfway, and why no model call is ever repeated.
Stored before it moves on
Sessions live in <agent>/.egin/egin.db, a SQLite database. Every user message, model reply, tool call and tool result is written there before the loop takes the next step.
The loop is driven only by those stored messages. It does not keep state in memory that the database does not have. So when a process dies, nothing is lost but the step that was in flight.
Resuming
egin serve resumes interrupted sessions when it starts. From the command line, resume one with its id:
egin run my-agent --session <id>
A completed model call is never made twice: its reply is already stored, so the loop picks up from the first step that did not finish.
Side effects of an interrupted call
The hard case is a tool call that was running when the process died. It may have finished, half-finished, or never started.
egin does not re-run it blindly. The model is told the call was interrupted and its effects are unknown, and it checks the state first: lists the directory, reads the file, queries the service. Then it decides what to do. Read-only tools have no effects to worry about, so they are simply run again. So are durable tools: each keeps a journal of the steps it finished, and skips them when it runs again.
Approvals survive too
An approval request is stored like everything else. If the server restarts while waiting for an answer, the request is still there, and the answer is stored when it comes, even if it comes before the run has been picked up again. The same holds for ask_user questions, and for messages sent during a run: they wait in the session’s inbox until the run takes them up.
Several processes, one folder
Several egin processes can share one agent folder, for example egin serve and an egin eval run. SQLite serialises their writes; a writer waits up to 60 seconds for the lock.
A running session holds a lease, renewed every 10 seconds by the process running it. When egin serve starts, it resumes only sessions whose lease has lapsed for 30 seconds: one another process is still running is left alone, and taken over only if that process stops. So a session interrupted moments before a restart resumes up to 30 seconds later.
Subagents
A subagent’s session runs inside its parent’s. Cancelling the parent cancels any subagent it is running. After a restart, egin doesn’t resume a subagent’s session on its own: the parent resumes, its interrupted task call tells the model the subagent didn’t finish, and the model decides whether to start it again.