Sessions

A session is one conversation with one agent, rooted in a directory on one machine. Sessions are the unit of state in Consortium.

Local and remote control

A session is either controlled locally (you’re typing in the terminal that launched it) or remotely (you’re driving it from the app).

• Launch consortium claude and the session starts local.
• Send it a message from your phone or the web app and the local process hands over: the session restarts in remote mode and keeps running under the daemon.
• Take it back at the keyboard: press any key in the original terminal (for Consortium Code sessions, double-tap space). The prompt returns with full context.

What persists

• The full message history, end-to-end encrypted, with per-session monotonic sequence numbers.
• Session metadata and agent state (also encrypted), with optimistic version checks so concurrent writers can’t clobber each other.
• Attachments and artifacts, stored encrypted and referenced by ID.

Sessions live until you delete them. If the machine goes offline, the session is marked inactive (machines time out after ~10 minutes without a heartbeat) and resumes when its daemon reconnects.

What does not persist

• The agent’s process memory. On daemon restart the agent is re-spawned and rebuilds from persisted history.
• Anything you never sent: BYOK keys are injected into the agent process environment and are not part of session state.

Ordering, gaps, and caching

Clients track the last update sequence they’ve seen. On a gap (missed socket update), the app schedules a coalesced recovery that re-syncs the session list and delta-fetches only messages newer than what it holds. Message history is cached on-device (write-through), so reopening a session hydrates instantly before the network round-trip.

Key rotation

Each session’s content is encrypted under its own data-encryption key. Rotating the key (e.g. after revoking access) bumps its version — old wrapped copies of the key stop working, and previously distributed ciphertext can’t be decrypted by revoked parties going forward.

Idempotent sends

Messages carry a client-generated localId, unique per session — retries after flaky connections can’t double-post.