Decisions, trade-offs, limitations, and an honest roadmap

This is a ledger, not a claim that T3 Code found the one right architecture. At the locked revision, its choices consistently put one environment server in charge of product authority, preserve accepted intent in SQLite, and make provider-native execution, filesystem work, and client presentation explicitly separate. That produces a comprehensible control surface across many harnesses. It also produces real seams: a committed event can miss a hot reactor, an external harness can cross an ambiguous crash boundary, and not every client or retained artifact has equal capabilities.

Use the six columns throughout this chapter precisely:

1. Authority and durable intent: make the environment server the product boundary

Server authority

The pressure is remote control without pretending that a browser, desktop shell, or phone owns a provider process, Git worktree, terminal, or filesystem. T3 puts those operations behind the environment server. Clients authenticate, use typed RPC, and hold projections and presentation state; a provider still owns its native reasoning and context engine. This makes one environment the place where authorization, orchestration, workspace effects, and product history meet.

The benefit is a clear remote model: adding another device adds another client of an environment rather than another competing owner of a workspace. The cost is that availability, upgrades, and recovery concentrate around that server; clients must reconnect and reconcile instead of making local state authoritative. A peer-to-peer or client-owned model could improve disconnected autonomy, but would need a conflict, credential, and workspace-execution story that this implementation deliberately does not carry. Revisit the choice if concurrent offline editing or multi-writer workspace authority becomes a primary product requirement.

Transactional event core

The pressure is accepting a user command exactly enough to answer a retry without claiming provider completion. The choice is a serialized engine that decides a command, appends its event batch, applies projections, and records the command receipt inside one SQLite transaction. The benefit is a sharp acceptance boundary: retrying the same command id can recover the stored result, and a failed transaction leaves no accepted receipt. The cost is that normalization-time files, provider calls, and later reactor work are outside that transaction.

        const committedCommand = yield* sql
          .withTransaction(
            Effect.gen(function* () {
              const committedEvents: OrchestrationEvent[] = [];
              let nextCommandReadModel = commandReadModel;
 
              for (const nextEvent of eventBases) {
                const savedEvent = yield* eventStore.append(nextEvent);
                nextCommandReadModel = yield* projectEvent(nextCommandReadModel, savedEvent);
                yield* projectionPipeline.projectEvent(savedEvent);
                committedEvents.push(savedEvent);
              }
 
              const lastSavedEvent = committedEvents.at(-1) ?? null;
              if (lastSavedEvent === null) {
                return yield* new OrchestrationCommandInvariantError({
                  commandType: envelope.command.type,
                  detail: "Command produced no events.",
                });
              }
 
              yield* commandReceiptRepository.upsert({
                commandId: envelope.command.commandId,
                aggregateKind: lastSavedEvent.aggregateKind,
                aggregateId: lastSavedEvent.aggregateId,
                acceptedAt: lastSavedEvent.occurredAt,
                resultSequence: lastSavedEvent.sequence,
                status: "accepted",
                error: null,
              });
 
              return {
                committedEvents,
                lastSequence: lastSavedEvent.sequence,
                nextCommandReadModel,
              } as const;
            }),
          )
          .pipe(
            Effect.catchTag("SqlError", (sqlError) =>
              Effect.fail(
                toPersistenceSqlError("OrchestrationEngine.processEnvelope:transaction")(sqlError),
              ),
            ),
          );
 
        commandReadModel = committedCommand.nextCommandReadModel;
        for (const [index, event] of committedCommand.committedEvents.entries()) {
          yield* PubSub.publish(eventPubSub, event);
          if (index === 0) {
            yield* Metric.update(
              Metric.withAttributes(
                orchestrationCommandAckDuration,
                metricAttributes({
                  ...baseMetricAttributes,
                  ackEventType: event.type,
                }),
              ),
              Duration.millis(Math.max(0, (yield* Clock.currentTimeMillis) - envelope.startedAtMs)),
            );
          }
        }
        return { sequence: committedCommand.lastSequence };

An append-only log is not free: commands and deciders must retain invariants, read models must be maintained, and a receipt is not an end-to-end idempotence proof for a multi-step bootstrap saga. A direct CRUD model could lower local complexity when there is no need to replay or compose state. Revisit the event core when the product no longer benefits from immutable command history, independently shaped projections, or receipt-based retry semantics.

flowchart LR
  C[Authenticated client] --> S[Environment server
authority]
  S --> T[(Event + projection + receipt
SQL transaction)]
  T -. committed event .-> R[Hot reactor]
  R --> A[Provider adapter]
  A --> P[Native harness / process]
  T --> Q[Projection cursors
rebuild read models]
  C --> O[Mobile durable
intent outbox]
  S --> U[Exact-version
stage + preflight]
  C -. retained demand .-> B[Scoped background work]
  R -. no durable delivery record .-> X[Crash / replay seam]
  A -. native state remains external .-> X
  P -. result returns hot .-> R

2. Delivery and read state: choose explicit eventual boundaries

Hot, best-effort post-commit reactors

The pressure is to avoid calling a harness while a domain transaction is still open. T3 publishes only after commit, then runs provider, runtime-ingestion, checkpoint, deletion, and awareness consumers as hot scoped workers. The benefit is simple: rollback cannot have caused a provider turn, and one reactor failure is handled without rolling back accepted domain history. The cost is the reactor crash window. A process can die after the receipt/event commit and before a reactor observes it; the source contains no durable outbox row, per-reactor delivery cursor, or startup replay of pending hot work.

That is a reasonable trade where an external operation can be ambiguous to repeat: a durable outbox still needs idempotency keys, attempt records, and a policy for a harness that accepted work just before a crash. It would be the alternative when the product requires guaranteed post-commit execution. The reversal trigger is explicit: if “accepted turn” must eventually imply “provider send attempted” across server crashes, add a durable delivery protocol rather than describing the current reactor as exactly once.

Snapshot plus cursor

The pressure is a fast UI that can restart, replay, and subscribe without claiming that one monolithic snapshot is globally current. Each projector has a durable cursor; normal command acceptance advances its projector SQL and cursor together. A composed snapshot uses the minimum cursor among its required projectors, while live clients attach before their replay/snapshot read and use global event sequence for gap repair.

The benefit is independently shaped and rebuildable read state. The cost is more than one watermark, a bounded bootstrap path, ordering-sensitive projectors, and careful client race guards. A single authoritative document per thread could simplify some reads but makes fan-out and independently evolved views harder. Revisit cursor architecture if projection lag, cross-projector joins, or operational replay needs outgrow the current SQLite/replay ceiling.

3. Harness and client continuity: normalize the boundary, not the world

Provider adapters

The pressure is five harnesses with different session, approval, stream, context, and process semantics. T3 chooses a narrow adapter lifecycle and canonical runtime event grammar; ProviderService owns routing, bindings, correlation, credentials, and cross-provider policy. The benefit is one product domain that can preserve native provenance without forcing all harnesses into a fictional universal feature set.

The cost is an adapter matrix, capability gaps, and no repository-wide proof that all providers have semantic parity. A generic “agent protocol only” design could reduce some integrations but would either lose native features or push product policy into each provider driver. Revisit this boundary when the normalized contract can no longer represent an important native lifecycle without pervasive escape hatches.

One reconnect owner per environment

The pressure is multiple pages, caches, notifications, and devices observing one remote environment without creating retry storms or merging unrelated authorities. The choice is one environment registry entry with one supervisor generation and at most one active RPC lease; shell and thread synchronizers retain separate cache and cursor responsibilities. The benefit is one place to own transport lifecycle while each projection remains honest about its own authoritative refresh.

The cost is a sophisticated supervisor, generations, leases, and surface-specific resynchronization. A global connection manager is attractive but would blur separate environment authority and corrupt cache ownership. Revisit this model if the product adds genuine cross-environment aggregation or a shared write model—not merely a UI that displays several environment summaries.

Durable mobile intent outbox

The pressure is a phone losing foreground time or connectivity after the user has pressed send. Mobile uses an optimistic enqueue with durable persistence, serializes its manager, and asks the user for a delivery decision when a queued turn collides with a changed thread state. The benefit is preserving user intent locally before it can be delivered to an environment. The cost is another state machine: existence guards, capped backoff, confirmations, and explicit replay semantics instead of an assumption that a compose action immediately became a server turn.

An always-online client could omit this machinery, but it would trade away the recovery behavior that matters on a mobile lifecycle. Revisit the outbox when mobile intent becomes multi-device collaborative work requiring server-issued identities or when all clients need an equivalent durable intent queue.

  // The queued atom drives the composer's immediate "queued" feedback, so it
  // is published synchronously; the durable write happens behind it and rolls
  // the message back out if it fails (durability only matters for crash
  // recovery, not for the in-session queue).
  const enqueue = (message: QueuedThreadMessage): Promise<void> => {
    setMessages([
      ...currentMessages().filter((candidate) => candidate.messageId !== message.messageId),
      message,
    ]);
    return serialize(async () => {
      try {
        await options.storage.write(message);
      } catch (cause) {
        // Roll back by reference, not messageId: a retry enqueue with the same
        // id may have optimistically replaced this attempt while the write was
        // in flight, and its entry must survive this attempt's failure.
        setMessages(currentMessages().filter((candidate) => candidate !== message));
        throw new ThreadOutboxManagerError({
          operation: "enqueue",
          environmentId: message.environmentId,
          threadId: message.threadId,
          messageId: message.messageId,
          cause,
        });
      }
    });
  };
 
  // Resolves once all pending mutations (including any in-flight enqueue
  // write) have settled, reporting whether the message is still queued. The
  // drain awaits this before dispatching so a message whose durable write
  // later fails can never have been delivered first.
  const confirmQueued = (message: QueuedThreadMessage): Promise<boolean> =>
    serialize(async () => currentMessages().some((candidate) => candidate === message));

Exact-version updates

The pressure is a newly visible client asking a connected server to run an incompatible runtime. T3 publishes the exact CLI package before a release exposes the clients that can request it; a boot-service server rejects non-exact targets, stages and preflights that runtime, then hands activation to a stable launcher. The benefit is a precise compatibility target and a reversible SQLite-bound trial. The cost is release ordering, launcher protocol compatibility, and platform-specific update machinery.

A floating channel update can reduce operations friction but makes an update request less reproducible. Revisit the invariant if a compatibility protocol—not matching versions—becomes sufficient to prove safe server/client combinations.

Scope-driven background work

The pressure is staying useful while mobile is backgrounded without keeping every environment permanently active. Mobile background activity reports retained demand through reference-counted environment scopes. The benefit is a bounded reason for work to continue: a caller declares interest and releases it. The cost is that subscription ownership and lifecycle cleanup must be correct; background liveness is not a durable scheduler, and platform APIs constrain what actually runs.

An always-on global worker would simplify call sites but waste resources and make ownership leaks more damaging. Revisit scopes when the product needs a durable background-job contract with OS-managed scheduling and completion receipts.

4. Limitations are part of the architecture contract

The ledger above describes choices. This section records the places where their edges must stay visible in a design review.

Shipped asymmetries and discrepancies

Retention and cleanup are selected operations, not one erase button

Tombstoning a project or thread changes its projected visibility; it does not erase the append-only event history or command receipts. Thread revert removes selected derived messages, plans, activities, turns, attachment files, and later checkpoint refs, but retains event history and records the revert itself. The thread-deletion reactor performs best-effort provider and terminal cleanup; the web separately offers an orphan-worktree removal path. Provider binding deletion exists as a repository operation, yet no caller appeared in the inspected production sources. Hidden checkpoint refs likewise do not gain a repository-wide lifecycle reconciler simply because a thread is tombstoned.

Attachment cleanup has the opposite shape: normalizers write image bytes before command dispatch, while projectors perform later filesystem deletion after their SQL and cursor step. That reduces database/file coupling but makes cross-store atomicity unavailable. A rejected or retried command can leave an early file; a failed cleanup is logged, and a crash after cursor advancement can prevent that event from selecting the same cleanup again. This is shipped behavior, not a future garbage collection protocol.

DPoP replay defense records a replay marker under a hashed proof-derived key through exclusive secret creation. The source path establishes rejection of a duplicate marker. Inference: the inspected source does not show a corresponding marker-expiry or retention sweep, so this book cannot claim a bounded replay-marker store merely because proof timestamps are recorded. That is a retention inference, not a security weakness claim.

The only roadmap claims here are explicit upstream future work

The internal remote document labels three items unbuilt: additional third-party tunnel endpoint providers, a relay-hosted OAuth callback broker, and richer multi-environment UI beyond the current connections list. They are future work, not dates, milestones, or a promise that their current design will ship. The pinned code and connect documentation do implement a hosted static /connect/callback handoff page. That is not evidence of a relay-hosted backend broker: only the broad claim that there is no callback path is stale, while the literal broker item remains future work.

5. A decision review is more useful than a pattern checklist

When evaluating T3 Code’s choices, the useful question is not “should every system copy this?” It is: which pressure does this choice address, which boundary is durable, and which cost does it impose? T3’s strongest recurring lesson is truthful separation: accepted intent is not provider completion; a projection is not a universal snapshot; a remote notification is not authority; a bounded local record is not a retention policy; and a compatibility branch is not a roadmap.