T3 Code keeps execution in the environment that owns the workspace. Web, desktop, and mobile clients control it over authenticated RPC. A remote client must never substitute its own filesystem, provider credentials, or machine state for the environment's. The desktop app bundles a server, but its renderer follows the same boundary.
Provider processes, terminals, Git, and project files belong to the server. Shared connection and
domain state belongs in packages/client-runtime; clients supply platform services and UI.
Keeping that logic shared prevents reconnect and multi-environment behavior from diverging between
web and mobile. See connection runtime and
remote environments.
The RPC contract is the boundary between independently versioned clients and servers. Subscriptions send the state a client needs, so a client viewing one thread does not pay for every thread's history. Authentication of a socket does not authorize every method on it. See environment auth.
Provider-specific behavior belongs behind an adapter. Orchestration works with normalized commands and events, so adding a provider should not require branches throughout the domain or clients. See provider constraints.
The event log is the source of truth for orchestration state. The v2 orchestrator serializes commands and decides events without performing provider or filesystem work. EventSink commits events, persisted projections, the accepted command receipt, and outbox effects in one database transaction. Subscribers receive events after that commit. This keeps command retries idempotent and prevents a persisted projection from getting ahead of the event log.
The effect worker performs side effects after intent has been recorded, then feeds results back into orchestration. A command acknowledgement therefore means the intent committed, not that the provider, checkpoint, or other follow-up work finished. Keep external I/O out of command decisions and the database transaction. Effects tied to a lost provider process cannot simply replay; recovery retires them before admitting new work.
Persisted events must remain decodable on replay. Changing a schema affects old environments at startup as well as live RPC traffic. Compatibility work must account for stored history, not just what the newest client sends.
A provider turn ending and its follow-up work settling are separate milestones. Orchestration records provider turn and run state independently from run finalization. A late checkpoint or diff must not extend the recorded provider duration or keep the client showing provider work as active. PR discovery after completion also checks that the checkout still matches the thread's non-default branch and that a newer run is not active.
Checkpoints use hidden Git refs to capture workspace state without adding commits to the user's branch. A revert must coordinate workspace state with the provider conversation. A provider that cannot roll back its conversation must reject that operation before changing the filesystem.
Thread settlement is server-owned. The
settlement service evaluates PR
and inactivity settings without a connected client. Merge notifications invalidate cached PR state
and trigger a check. The guarded thread.auto-settle command rejects newer activity, explicit
settlement overrides, and live or blocked work. It records the activity timestamp for stable
sorting and detaches idle provider sessions. Clients render the persisted result; they do not
derive settlement from their own clocks or PR caches.
Tests use drainable workers to wait until both the queue and its current item have finished. An empty queue alone does not prove the worker is idle.
V2 tests also drain the effect worker or await a specific persisted event or receipt. Test signals are separate from the durable command receipts that make dispatch idempotent. Production behavior must use persisted state and events, not test instrumentation or assumptions about elapsed time.
See the glossary for shared terms and the development runbook for setup and checks.