A session is a row in a registry plus a transcript on disk. Its subprocess exists only while it is working. Sessions are resumable rather than resident, because a pool of warm ones does not scale and resuming a cold one is quick.
Three identifiers
They are not interchangeable, and confusing two of them is the easiest mistake to make here.
| Identifier | Who mints it | What it is authority over |
|---|---|---|
| Session id | Turret, at creation | Every surface the app has: windows, the sidebar, the orchestration tools |
| Transcript id | The CLI | The transcript on disk, and every session function the SDK offers |
| Transcript path | The CLI | Nothing. It is derived, and the app never assembles it by hand |
Turret names a session before any process exists, so a sidebar row and a window are there ahead of the first token. The two ids start equal and can diverge later: a fork mints a new transcript id, and a conversation reset asks the surface to mount a fresh transcript. The session id never changes for the life of a row.
The mailbox
Every session is given an async stream as its prompt rather than a string, because interrupting, changing the model and changing the permission mode are all control requests that do nothing on a string. That stream is the session's mailbox.
A message pushed while a turn is running queues and runs at the next turn boundary. Interrupting does not clear the queue — the interrupt names the messages that are still going to run, and cancelling them is a separate act.
Worktrees
A session can open on a new git worktree instead of a directory that already exists.
The worktree is made by Claude Code's own WorktreeCreate hook, so a
Turret session and a claude --worktree session in the same repository get
the same tree, the same branch and the same environment.
With no hook configured, Turret makes the worktree Claude Code would have made. With one configured, the hook wins and there is no fallback behind it. A machine whose hook allocates ports, databases and state paths per worktree must not have some other program quietly making worktrees a different way.
Sessions reaching each other
Spawning, messaging and scheduling another session are tools like any other, served by the app itself rather than by a mode. They run in the same process as the session registry, which is the reason the whole thing is built on the TypeScript SDK: a tool handler and the registry it reads sit on the same side of every process boundary.