T3 Code: how session transcripts are stored and resumed
Part of Session Store Research. Produced by running RESEARCH_PROMPT. Evidence snapshot: local checkout of pingdotgg/t3code (checked out from the TrogonStack/t3code fork) at commit b4b66491e39a9dd72e7f52de47a10cb5c41dc78a (committed 2026-07-21), the source of "T3 Code", a web GUI that wraps coding-agent CLIs (Codex, Claude, Cursor, OpenCode). Every citation below was re-verified against this exact commit on 2026-07-23 (working tree clean). Citations use repo-relative path:line shorthand.
Unlike most products in this corpus, T3 Code does not run the model itself: it orchestrates provider CLIs and is, structurally, a CQRS / event-sourced orchestration server written in TypeScript on the Effect runtime. The durable "session" is therefore split across two tiers: T3's own append-only event log (the orchestration truth) and the provider CLI's native conversation memory (referenced by an opaque resume cursor). The persistence subsystem lives under apps/server/src/persistence/ (the event store, migrations, projection repositories) and apps/server/src/orchestration/ (the decider, projector, engine, and reactors).
The storage model
The durable session is an append-only event log: the SQLite table orchestration_events in a single per-server database {baseDir}/userdata/state.sqlite (apps/server/src/config.ts:101-105, stateDir is userdata in prod / dev in dev, dbPath = join(stateDir, "state.sqlite")). The database opens in WAL mode with foreign keys on (apps/server/src/persistence/Layers/Sqlite.ts:36-37). The event store's own docstring states its role plainly: it "owns durable append/replay access to the orchestration event stream. It does not reduce events into read models or apply command validation rules" (apps/server/src/persistence/Services/OrchestrationEventStore.ts:4-6).
The event row is the source of truth (apps/server/src/persistence/Migrations/001_OrchestrationEvents.ts:8-23):
CREATE TABLE IF NOT EXISTS orchestration_events (
sequence INTEGER PRIMARY KEY AUTOINCREMENT,
event_id TEXT NOT NULL UNIQUE,
aggregate_kind TEXT NOT NULL,
stream_id TEXT NOT NULL,
stream_version INTEGER NOT NULL,
event_type TEXT NOT NULL,
occurred_at TEXT NOT NULL,
command_id TEXT,
causation_event_id TEXT,
correlation_id TEXT,
actor_kind TEXT NOT NULL,
payload_json TEXT NOT NULL,
metadata_json TEXT NOT NULL
)This is unambiguously session-as-log (event-sourced). There are two aggregate kinds -- project and thread (packages/contracts/src/orchestration.ts:899) -- and a "session" in product terms is a thread (OrchestrationThread, packages/contracts/src/orchestration.ts:347-381), reconstructed by folding the thread-scoped events of one stream_id.
What is authoritative vs. derived:
- Authoritative:
orchestration_events. It is append-only; nothing rewrites or deletes rows on the normal path. - Derived / rebuildable: the whole
projection_*family of tables (projection_projects,projection_threads,projection_thread_messages,projection_thread_activities,projection_thread_sessions,projection_turns,projection_pending_approvals, plus the projector cursor tableprojection_state,apps/server/src/persistence/Migrations/005_Projections.ts). Each is materialized by a projector that replays the log from its ownlast_applied_sequence(apps/server/src/orchestration/Layers/ProjectionPipeline.ts:1592-1606), so they are pure projections and fully rebuildable. - External runtime handle (not the log, not a projection): the
provider_session_runtimetable holds a per-thread opaqueresume_cursor_jsonthat points into the provider CLI's own native session store (apps/server/src/persistence/Migrations/004_ProviderSessionRuntime.ts:8-18,apps/server/src/persistence/ProviderSessionRuntime.ts:50). The actual model-side transcript for, e.g., a Codex thread lives in Codex's store; T3 references it by cursor. - Content-addressed side store: git-ref checkpoints of the working tree per turn, with a diff cache table
checkpoint_diff_blobs(apps/server/src/persistence/Migrations/003_CheckpointDiffBlobs.ts), plus attachment blobs under{stateDir}/attachments(config.ts:106).
Keying and identity
- Store scope: one
state.sqliteper server install/base directory (config.ts:101-105). There is no cwd- or project-path-encoded key in the event key; all projects and threads share one DB and are separated by columns. - Event key:
(aggregate_kind, stream_id, stream_version)with a global monotonicsequence.stream_idis aProjectIdorThreadId(OrchestrationEventStore.tsSchema.Union([ProjectId, ThreadId]),apps/server/src/persistence/Layers/OrchestrationEventStore.ts:53-54; event base fieldspackages/contracts/src/orchestration.ts:1101-1111). - Id minting: all ids are branded, trimmed, non-empty strings (
packages/contracts/src/baseSchemas.ts:26-60). Command-facing ids (commandId,threadId,projectId,messageId) are client-supplied; the server mintseventIdas a UUIDv4 viacrypto.randomUUIDv4(apps/server/src/orchestration/decider.ts:41-50). No id encodes ordering or location -- ordering comes entirely fromsequence(global) andstream_version(per aggregate), not from the id. - Listing scope: global within the DB. Threads are scoped to a project by
project_id; a project is anchored to aworkspaceRootfilesystem path (OrchestrationProject,packages/contracts/src/orchestration.ts:211-222). - Relocation / rename: a thread's
branchandworktreePathare mutable fields carried bythread.meta-updatedevents (decider.ts:417-452, projectorprojector.ts:388-405); moving the working directory does not change identity because the key is thethreadId, not a path. Title/model renames are likewisethread.meta-updatedevents.
The store interface
The event store is a pluggable service (an Effect Context.Service), so the contract is exported verbatim (apps/server/src/persistence/Services/OrchestrationEventStore.ts:22-55):
export interface OrchestrationEventStoreShape {
readonly append: (
event: Omit<OrchestrationEvent, "sequence">,
) => Effect.Effect<OrchestrationEvent, OrchestrationEventStoreError>;
readonly readFromSequence: (
sequenceExclusive: number,
limit?: number,
) => Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError>;
readonly readAll: () => Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError>;
}append assigns sequence and stream_version at insert time and returns the stored event; readFromSequence is an exclusive-cursor paged replay; readAll is readFromSequence(0, MAX_SAFE_INTEGER) (apps/server/src/persistence/Layers/OrchestrationEventStore.ts:184-267). The store never validates commands or builds read models.
The write side that callers actually use is the OrchestrationEngine service (apps/server/src/orchestration/Services/OrchestrationEngine.ts), whose reconstructed contract is:
dispatch(command) -> Effect<{ sequence }, OrchestrationDispatchError>-- the single mutation entrypoint. It enqueues onto a single-writer command queue and awaits the result (Layers/OrchestrationEngine.ts:318-327).readEvents(fromSequenceExclusive, limit) -> Stream<OrchestrationEvent>-- thin pass-through toeventStore.readFromSequence(Layers/OrchestrationEngine.ts:315-316).streamDomainEvents -> Stream<OrchestrationEvent>-- a fresh PubSub subscription per consumer for live fan-out (Layers/OrchestrationEngine.ts:335-337).
Supporting durable repositories (each its own Context.Service, reconstructed):
- Command receipts (idempotency ledger):
upsert(receipt),getByCommandId({commandId}) -> Option<receipt>(apps/server/src/persistence/Services/OrchestrationCommandReceipts.ts:44-63), backed by table fromMigrations/002_OrchestrationCommandReceipts.ts. - Projection repositories (one per read-model table) plus a
ProjectionStatecursor repo, driven by the pipeline'sbootstrapandprojectEventoperations (Services/ProjectionPipeline.ts,Layers/ProjectionPipeline.ts:1608-1644). - ProjectionSnapshotQuery:
getSnapshot()andgetCommandReadModel()build the full read model from the projection tables in one transaction (apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts:954-1243). - ProviderSessionRuntimeRepository:
upsert,getByThreadId,list,deleteByThreadIdover the opaque resume-cursor rows (apps/server/src/persistence/ProviderSessionRuntime.ts:64-103).
The client-facing RPC surface over WebSocket is orchestration.dispatchCommand, orchestration.replayEvents, orchestration.subscribeThread, orchestration.subscribeShell, orchestration.getTurnDiff, orchestration.getFullThreadDiff, orchestration.getArchivedShellSnapshot (packages/contracts/src/orchestration.ts:25-33, 1341-1370).
Write and append path (ordering, durability, concurrency, delivery)
Commit shape: a command is decided into one or more events by a pure decider (
decideOrchestrationCommand(command, readModel),apps/server/src/orchestration/decider.ts:97-876), then each event isINSERTed. The append computes the next per-stream version inline (apps/server/src/persistence/Layers/OrchestrationEventStore.ts:106-157):sqlCOALESCE( (SELECT stream_version + 1 FROM orchestration_events WHERE aggregate_kind = ? AND stream_id = ? ORDER BY stream_version DESC LIMIT 1), 0)Ordering: two levels.
sequence INTEGER PRIMARY KEY AUTOINCREMENTis the global order;stream_versionis the per-aggregate order, enforced unique byidx_orch_events_stream_version ON (aggregate_kind, stream_id, stream_version)(Migrations/001_OrchestrationEvents.ts:26-28). That unique index is the optimistic-concurrency guard: two events cannot occupy the same stream version.Atomicity:
OrchestrationEngine.processEnvelopewraps the whole command insql.withTransaction: for each planned event it appends, folds it into the in-memory command read model, runs the projection pipeline, then upserts the command receipt -- all in one transaction (Layers/OrchestrationEngine.ts:175-219). So the log append and the SQLite projections commit together (WAL,Sqlite.ts:36).Concurrency: single-writer per server. Every command flows through one unbounded queue consumed by exactly one worker fiber (
Layers/OrchestrationEngine.ts:96,309-310), so commands are strictly serialized. There is no caller-supplied expected-version precondition; OCC is implicit in the single-writer queue plus the uniquestream_versionindex.Delivery / idempotence: exactly-once command application via the command-receipt ledger. Before deciding, the engine looks up the receipt by
commandId: anacceptedreceipt short-circuits and returns the storedresultSequence; arejectedreceipt fails fast; otherwise it proceeds and writes a new receipt inside the same transaction (Layers/OrchestrationEngine.ts:144-157,196-204). SincecommandIdis client-supplied, a retried dispatch is deduplicated. On dispatch failure the engine reconciles its in-memory read model by re-reading persisted events from the pre-dispatch sequence (Layers/OrchestrationEngine.ts:119-132,270-298).
Read and resume path
- Server startup: projections are bootstrapped by replaying the log from each projector's
last_applied_sequence(Layers/ProjectionPipeline.ts:1592-1606), then the engine seeds its in-memory command read model from the projection tables, not from a full replay (getCommandReadModel,Layers/OrchestrationEngine.ts:306-307). So resume of the engine reads the derived projections; the log is replayed only to fill any projector gap. - Client resume:
subscribeThread/subscribeShelltake an optionalafterSequencecursor. When present, the server skips the full snapshot and replays events after that sequence before switching to live streaming; overlapping events are deduped by sequence on the client (packages/contracts/src/orchestration.ts:474-508). Without a cursor, the server sends a full projection snapshot (getSnapshot,ProjectionSnapshotQuery.ts:954-1243) then live events. A raworchestration.replayEventsRPC reads the log from a sequence (orchestration.ts:1333-1339). - Provider conversation resume is a separate tier: the model-side transcript is not in T3's log. Resuming the underlying agent uses the opaque
resumeCursorfromprovider_session_runtimehanded back to the provider adapter (ProviderSessionRuntime.ts:50; Codex resume/fork returns aCodexResumeCursor { threadId },apps/server/src/provider/Layers/CodexAdapter.ts:1667). - Bounds / pagination: event replay pages at
READ_PAGE_SIZE = 500with a default limit of1_000(Layers/OrchestrationEventStore.ts:67-68). Read-model materialization is capped:MAX_THREAD_MESSAGES = 2_000,MAX_THREAD_CHECKPOINTS = 500(apps/server/src/orchestration/projector.ts:33-34), activities capped at 500 and proposed plans at 200 (projector.ts:734,579). These caps bound the view, not the log.
Listing, summaries, and search
- Listing is a set of SQL queries over the projection tables, not a directory scan or a log replay. The shell snapshot lists
projection_projectsandprojection_threads(ProjectionSnapshotQuery.ts:300-420), and the thread row is denormalized with picker-facing summary fields:latest_user_message_at,pending_approval_count,pending_user_input_count,has_actionable_proposed_plan,latest_turn_id,archived_at(ProjectionThreadShell,packages/contracts/src/orchestration.ts:403-428; columns added by later migrations, e.g.023,017,033). No scale numbers are quoted in-source. - Summary consistency: the projection row is the denormalized read model. It is kept consistent by being written in the same transaction as the log append on the live path (
Layers/OrchestrationEngine.ts:184), and each projector records itslast_applied_sequenceinprojection_stateatomically with its own writes (Layers/ProjectionPipeline.ts:1568-1578), so a projector can resume exactly where it left off. - Search: there is no full-text or vector search subsystem (in contrast to Hermes's FTS5). Discovery is ordinary SQL filtering over the projection tables; there is nothing to bootstrap or keep in sync beyond the projections themselves.
Entry/message structure and versioning
- Event envelope (
packages/contracts/src/orchestration.ts:1101-1111):sequence,eventId,aggregateKind,aggregateId,occurredAt(ISO string),commandId,causationEventId,correlationId,metadata, plus a discriminanttypeand a per-typepayload.metadatacarries provider provenance (providerTurnId,providerItemId,adapterKey,requestId,ingestedAt,orchestration.ts:1092-1098). There are 23 event types (OrchestrationEventType,orchestration.ts:872-897), each with a typed payload schema and a corresponding union member (OrchestrationEvent,orchestration.ts:1113-1230). - Store interpretation:
payloadandmetadataare persisted as JSONTEXT(payload_json,metadata_json), so the row is opaque bytes at rest, but the store decodes and validates them through Effect Schema on both append and read (decodeEvent,Layers/OrchestrationEventStore.ts:31-33,204-208). The store also derivesactor_kind(client/server/provider) from the command id prefix and metadata (inferActorKind,Layers/OrchestrationEventStore.ts:70-90). Dedup/identity keys:event_id(UNIQUE) for the event,command_idfor command idempotency. - Chaining:
causationEventIdlinks an event to the event that caused it -- e.g.thread.turn-start-requestedis stamped with thethread.message-sentevent's id as its cause (decider.ts:557).correlationIdis by design the originatingcommandId(orchestration.ts:146-148). Thread lineage is carried in payload fields (parentThreadId,forkedFromThreadId,forkedUpToMessageId), not in envelope pointers. - Versioning: there is no explicit per-event schema-version field. Format evolution is handled additively by the schemas themselves --
withDecodingDefaultsupplies defaults for fields added later (e.g.runtimeMode,interactionMode,orchestration.ts:934-937), and a pre-decoding transform absorbs the legacy{provider}→{instanceId}model selection shape without a migration (ModelSelection,orchestration.ts:81-114). Because projections are rebuildable, read-model schema changes replay from the log. - DB schema migrations are a forward-only ratchet run at startup via
effect_sql_migrations, statically imported and sorted by id, applied only if greater than the last recorded id (apps/server/src/persistence/Migrations.ts:61-136). Migrations run 1–33 then jump to 41 (Migrations.ts:61-96), a gap not explained in-source. No down-migrations exist.
Compaction and history management
- There is no compaction, summarization, or truncation of the event log. The durable
orchestration_eventsstream grows monotonically. The only "shrinking" is view-side: read-model materialization caps (MAX_THREAD_MESSAGES = 2_000etc.,projector.ts:33-34,484) bound what the UI holds, not what is stored. - Model-visible context compaction is an upstream / provider concern: the wrapped CLI manages its own context window. T3 records the outcome of turns as events but does not compact them.
- The one summarization primitive is summary-mode fork (below), which produces a single new assistant message in a new thread rather than rewriting the source thread's history.
Rewind, checkpoints, and fork
- Rewind/revert is expressed as appended events, interpreted at fold time -- never a destructive edit. A
thread.checkpoint.revertcommand produces athread.checkpoint-revert-requestedevent (decider.ts:649-669); the CheckpointReactor restores the working tree and then dispatchesthread.revert.complete, producingthread.reverted(decider.ts:816-835). The projector foldsthread.revertedby filtering the view to entities whosecheckpointTurnCount <= turnCount-- dropping later messages, activities, proposed plans, and checkpoints from the projection while the underlying events remain in the log (projector.ts:665-714). This is exactly the append-marker-replayed pattern (as opposed to Hermes's in-place flag mutation). - File-state checkpoints are git-ref based, one per
(thread, turnCount). The CheckpointReactor captures a real git checkpoint when a turn completes, keyed bycheckpointRefForThreadTurn(threadId, turnCount), and only in a git workspace (apps/server/src/orchestration/Layers/CheckpointReactor.ts:177-319). The turn's file summary andcheckpointRefare carried inthread.turn-diff-completed(ThreadTurnDiffCompletedPayload,orchestration.ts:1076-1085); the full diff text is cached incheckpoint_diff_blobs(Migrations/003_CheckpointDiffBlobs.ts). File content is therefore stored/deduped by git (content-addressed refs), not inlined in the event log. - Fork is a two-phase, copy-plus-lineage operation into a new stream. A
thread.forkcommand must go throughThreadForkService-- the plain decider explicitly rejects it (decider.ts:264-269). The service attempts a native provider fork first (Codex advertisescapabilities.nativeFork: trueand itsforkThreadreturns a new provider thread id as the resume cursor,CodexAdapter.ts:1647-1667,1759), then dispatchesthread.fork.finalize, which the decider turns into athread.forkedevent (decider.ts:271-348). Forfull-historymode the source messages up to the cutoff are copied into the new thread; forsummarymode a single generated assistant summary message is produced (decider.ts:283-320). Thethread.forkedpayload recordsforkedFromThreadId,forkedUpToMessageId,forkMode, andpendingForkContextText(injected ahead of the first prompt when the new thread has no native provider memory), and the projector inserts the new thread with its copied messages (projector.ts:309-353).
Subagents and nested sessions
- A subagent is a first-class sibling thread in the same project, not nested storage and not entries in the parent transcript. It gets its own
threadId(its own event stream) and is linked to its parent byparentThreadId, carried onthread.created(ThreadCreatedPayload.parentThreadId,orchestration.ts:940; projectorprojector.ts:286). The design is documented in the fork ADR: "each subagent appears as its own thread: openable, inspectable mid-flight, steerable, and resumable" (docs/fork/0003-native-subagent-threads.md). - Subagents can run on a different provider/model than the parent, and each defaults to its own git worktree; read-only children can share the parent's checkout (
docs/fork/0003). - Nesting is bounded: "subagent trees can nest up to five levels deep, and at most eight subagents may run at once across a tree" (
docs/fork/0003). These guardrails live in the delegation/tool layer, not in the store schema. - Parent delete:
thread.deletedtriggers only that thread's runtime cleanup (stop provider session, close terminals withdeleteHistory: true) via the ThreadDeletionReactor (apps/server/src/orchestration/Layers/ThreadDeletionReactor.ts:44-64). No cascade to child threads was found in the event/decider path -- children keep theirparentThreadIdand would be orphaned rather than cascade-deleted (see Open questions).
Retention, deletion, and multi-host
- Retention: none. No TTL, lifecycle sweep, or scheduled cleanup of
orchestration_eventsor projections was found. The log is retained indefinitely. - Deletion is command-driven and soft in the read model, physical only for external artifacts.
project.deletefans out tothread.deletefor each active thread and then deletes the project, as one decided command sequence (decider.ts:184-227). Athread.deletedevent is appended (the event itself is never removed); the projector setsdeleted_aton the projection row and schedules physical removal of that thread's attachment directory as a projector side-effect (deletedThreadIds→deleteThreadAttachments,Layers/ProjectionPipeline.ts:436-463); the ThreadDeletionReactor best-effort stops the provider session and deletes terminal history (ThreadDeletionReactor.ts:44-64). Snapshot queries filterdeleted_at IS NULLfor active listings (ProjectionSnapshotQuery.ts:381). - Multi-host: not a first-class path. The model assumes a single server process holding one local
state.sqlite(single-writer command queue,Layers/OrchestrationEngine.ts:96,309-310). Remote access is a networking concern -- the server is exposed over Tailscale/SSH (thetailscaleandsshpackages,docs/architecture/remote.md) -- but the database is never shared across hosts, and there is no distributed coordination or remote writeback.
Interop with foreign session stores
T3 Code's entire purpose is to drive foreign agent CLIs (Codex app-server, Claude Code, Cursor CLI, OpenCode), so it interoperates at the runtime level rather than the storage level. It does not discover, import, or parse those CLIs' native on-disk session files. Instead, for each thread it stores an opaque resume_cursor_json in provider_session_runtime (Migrations/004_ProviderSessionRuntime.ts:15, ProviderSessionRuntime.ts:50) and delegates start/resume/fork to the provider adapter, which reconstitutes the provider's own session from that cursor (CodexResumeCursor { threadId }, CodexAdapter.ts:1667). The provider CLI remains the owner of the raw model transcript; T3's event log is the orchestration layer over it. The provider_session_runtime row is a mutable upsert-by-threadId record (ProviderSessionRuntime.ts:150-187), not part of the append-only log.
What this implies for our Session Store (our inference)
(Our inference, clearly marked as such.) T3 Code is the corpus's cleanest event-sourced example: the durable session is an append-only orchestration_events log keyed by (aggregate_kind, stream_id, stream_version) with a global sequence, and every list/summary/detail view is a rebuildable SQLite projection driven by per-projector last_applied_sequence cursors. This is almost exactly the shape our design targets, and it validates several specific choices:
- Decider/projector/read-model split with a single-writer command queue and a transactional append+project step is a working, coherent pattern (
decider.ts,projector.ts,Layers/OrchestrationEngine.ts:175-219). It gives OCC "for free" via a unique(aggregate_kind, stream_id, stream_version)index without a caller-supplied expected version -- worth contrasting with an explicit expected-version precondition, which would be needed the moment writers are no longer serialized by one process. - Command receipts keyed by client-supplied
commandIdare a clean, durable idempotence mechanism (exactly-once command application), directly addressing the crash-mid-write dedup gap that Hermes solved only with an in-memory marker. We should adopt an equivalent command/idempotency ledger. - Causation/correlation on every event (
causationEventId,correlationId = commandId) is a low-cost provenance backbone we should keep. - Retroactive operations as replayed events, not destructive edits (
thread.revertedfiltered at fold time,projector.ts:665-714) is the behavior our event-sourced design wants, and a strong precedent over Hermes's in-place flag mutation. - Two-tier custody is the most transferable idea here: T3 owns the orchestration facts in its event log but does not own the model transcript -- it stores only an opaque resume handle and delegates to the provider. This suggests our Session Store can be the authoritative orchestration log while the heavy raw transcript lives elsewhere, provided the durable log records the resume handle and enough provenance to re-derive views.
- Cautions: (1) no retention or log-truncation/snapshotting -- the log grows unbounded and projection bootstrap is a full replay from each cursor; our design needs an explicit snapshot/retention story that theirs lacks. (2) Fork is physical copy-plus-lineage into a new stream (
decider.ts:283-320), not a shared-prefix reference -- simple but O(history) per fork; our design could reference a shared event prefix instead. (3) Delete is soft in projections but events are retained forever, so "deleted" data is still fully present in the log -- a privacy/retention consideration we must decide deliberately.
Open questions
- Log growth / snapshotting: no truncation, compaction, or snapshot of
orchestration_eventswas found. Whether large installs ever bound the log or precompute projector snapshots (beyond the per-projector cursor) is unresolved. - Child cascade on parent delete:
thread.deletedcleanup targets only the deleted thread's runtime (ThreadDeletionReactor.ts:44-64); no cascade to subagent children was traced, so children appear to orphan (danglingparentThreadId). The intended lifecycle of children on parent delete/revert was not pinned down. - Migration id gap 33 → 41 (
Migrations.ts:94-95): whether 34–40 were dropped, renumbered, or reserved is not explained in-source. - Resume-cursor contents per provider: only
CodexResumeCursor { threadId }was traced (CodexAdapter.ts:1667); the cursor/runtime_payload_jsonshapes for Claude, Cursor, and OpenCode adapters were not fully enumerated. - Multi-process safety: correctness relies on a single server process's single-writer queue; the behavior if two server processes opened the same
state.sqlite(the uniquestream_versionindex would reject a clash, but the in-memory read models would diverge) was not exercised.
