Environment, project, thread, turn, and session
The entities share a UI, but they have different identity, cardinality, ownership, and restart behavior.
What this chapter resolves
- Distinguish product work items from provider and transport sessions.
- Understand which entity owns workspace, provider selection, history, and lifecycle.
- Separate durable thread state from ephemeral liveness and live plan progress.
T3 Code’s screens place projects, threads, turns, and provider sessions close together, but none are synonyms. The clean model starts with an environment: one running T3 server plus the machine and capabilities it exposes. A client can hold several environment descriptors and merge their work into one view.
The entity ladder
| Entity | Parent / cardinality | What it carries | Important boundary |
|---|---|---|---|
| Environment | client catalog → many | server identity, label, platform, version, capabilities, authenticated endpoint | one authority for the execution context it exposes; one physical host may expose several |
| Project | environment → many | workspace root, repository identity, scripts, presentation metadata | a discovered/configured root, not a task |
| Thread | project → many | workspace selection, provider instance/model/modes, messages, activities, plans, checkpoints, lifecycle | the durable product work item |
| Turn | thread → ordered many | one user request, provider lifecycle, generated assistant/tool activity, usage, checkpoint ordinal | a lifecycle episode, not necessarily a provider process |
| Provider session | thread → current binding | instance, cwd, model/runtime payload, continuation state, live adapter object when running | binding can survive; the live object cannot and may later be created from continuation state |
| Connection session | environment target → one attempt/lease | authenticated socket, capabilities, generation, sequence cursor | transport lifetime; reconnect replaces it without replacing the thread |
The thread is where product concepts converge. It identifies a project and workspace, remembers the chosen provider instance and modes, and projects messages, activities, proposed plans, checkpoints, and a summary of provider runtime state. The provider’s live session object remains outside that aggregate.
Similar names, different restart behavior
Which identity survives?
Select a disruption and inspect which layers change.
Scenario 1 of 3: Socket reconnect
Transport is replaced; domain identity stays
A new RPC session and connection lease can resume the same environment and thread.
- Environment, project, and thread IDs are unchanged.
- The client may resume after a sequence cursor or request an authoritative snapshot.
- The provider process does not restart merely because the phone changed networks.
- Socket reconnect · Transport is replaced; domain identity stays (Expected path)
A new RPC session and connection lease can resume the same environment and thread.
- Environment, project, and thread IDs are unchanged.
- The client may resume after a sequence cursor or request an authoritative snapshot.
- The provider process does not restart merely because the phone changed networks.
packages/contracts/src/environment.ts:31–92↗packages/client-runtime/src/state/threads.ts:534–645↗ - Server restart · Durable state returns; live objects do not (Caveat)
SQLite and filesystem state survive, while queues, PubSub, adapter objects, liveness, and active socket leases are gone.
- A persisted provider binding may later supply a continuation cursor.
- Projected starting/running sessions are reconciled because no live adapter session exists.
- Ephemeral agent liveness is rebuilt only from new runtime events.
packages/contracts/src/orchestration.ts:434–507↗apps/server/src/orchestration/ThreadBackgroundLiveness.ts:1–14↗apps/server/src/serverRuntimeStartup.ts:296–377↗apps/server/src/provider/Layers/ProviderService.ts:411–544↗ - New turn · The thread stays; the lifecycle advances (Alternative)
A turn adds ordered user/provider facts to the same work item and may reuse its provider continuation.
- The user message and turn-start intent form one event batch for an existing thread.
- Provider selection and compatibility decide whether the existing session can continue.
- Checkpoint turn count advances independently of connection lifetime.
apps/server/src/orchestration/decider.ts:926–1036↗packages/contracts/src/orchestration.ts:235–432↗
Startup and lazy recovery are two separate transitions. On boot, projected
starting or running sessions that have no live adapter entry are settled as an
error. A later routed operation may use the persisted binding and continuation
cursor to create or resume a new adapter session; the old in-memory object itself is
never resurrected.
A vocabulary rule for the rest of the book
When the text says session, it qualifies the owner: provider session, RPC session, browser auth session, or desktop backend process. When it says task, it means either the durable product work item—a thread—or explicitly a provider-emitted task/subagent activity. This avoids importing one harness’s internal vocabulary into the cross-provider domain model.