Server composition, activation, and readiness

Chapter 20 ended with one resolved ServerConfig. It does not get passed to a constructor that imperatively starts everything. runServer launches an Effect layer whose acquisition builds a graph of platform services, application services, routes, long-running roots, and release finalizers. A second mechanism—the activation barrier—controls when already-acquired roots may begin external work.

The server is a scoped graph

flowchart TB
  C[ServerConfig] --> P[Bun or Node platform]
  P --> DB[SQLite + migrations]
  P --> OS[filesystem · process · PTY · HTTP]
  DB --> D[persistence · auth · settings]
  D --> K[orchestration · providers · VCS · checkpoints]
  OS --> K
  K --> E[terminal · preview · workspace · cloud · telemetry]
  E --> R[HTTP API · assets · WebSocket RPC · MCP]
  R --> H[scoped HTTP server]
  A{{activation deferred}} -.opens after preparation.-> K
  A -.opens after preparation.-> E

The graph is broad because the environment server is the execution authority from Chapter 16. Composition still preserves boundaries: each service exposes a typed interface, layers declare requirements, and the launched scope owns acquisition and release. makeServerLayer is the composition root; Layer.launch keeps it alive.

SQLite is acquired before command traffic

The SQLite layer configures a busy timeout, enables foreign keys, selects WAL, and runs a statically ordered migration manifest during acquisition. At this revision the manifest contains 50 migrations. That number describes the implementation, not a compatibility promise for later revisions.

Four signals that sound similar but are not

The listener can therefore exist while every route effect waits behind global middleware; a separate FIFO startup queue also holds WebSocket-dispatched commands. That is intentional: routes need a real bound address before presentation and remote-access setup can be prepared, but external work must not race ahead of a candidate runtime that has not crossed its activation boundary.

      ),
    ))
      .filter(
        (binding) =>
          readServerUpdateContinuationTurnId(binding.runtimePayload) !== null &&
          readRuntimePayload(binding.runtimePayload).activeTurnId === null &&
          readRuntimePayload(binding.runtimePayload).continueAfterServerUpdatePrepared === true,
      )
      .map((binding) => binding.threadId),
  );
  const orphanedThreads = threads.filter(
    (thread) =>
      thread.session !== null &&
      (thread.session.status === "starting" ||
        thread.session.status === "running" ||
        thread.session.activeTurnId !== null ||
        (thread.session.status === "ready" && preparedThreadIds.has(thread.id))) &&
      !liveThreadIds.has(thread.id),
  );
 
  for (const thread of orphanedThreads) {
    const session = thread.session;
    if (session === null) {
      continue;
    }
    const binding = yield* directory.getBinding(thread.id).pipe(
      Effect.catchCause((cause) =>
        Cause.hasInterrupts(cause)
          ? Effect.failCause(cause)
          : Effect.logWarning("failed to read orphaned provider session directory binding", {
              threadId: thread.id,
              cause,
            }).pipe(Effect.as(Option.none())),
      ),
    );

After activate, the parked fibers are released concurrently. Heartbeat, browser/headless presentation, optional auto-bootstrap welcome, runtime-state persistence, and remote-access work may interleave with command admission and the ready publication. The flow orders the gate operations; it does not serialize all post-activation side effects.

Why park before activating?

forkParked is small but architectural. Its child fiber first fulfills a “parked” deferred and then waits on ServerActivation. The parent can prove all participating roots exist and are waiting before it releases a single shared gate. That prevents one early root from acting against a partially prepared graph.

This is synchronization, not a global transaction. Once activation opens, roots can perform filesystem, provider, Tailscale, cloud, browser, or other side effects with their own failure handling. Effect scopes provide release ownership; they do not magically roll back every effect that crossed an external boundary.

Provider, import, review, and device services

The server graph also assembles four control areas that deliberately remain outside the provider adapter itself. Model manifests and provider-auth services manage catalog and sign-in state. Agent-session scanners and importers turn selected native history into durable project/thread records. Pull-request synchronization observes linked reviews without making the Git host part of the orchestration transaction. DeviceService owns local and SSH hosts, targets, sessions, and frame/control traffic.

Keeping these as services preserves the narrow adapter rule: a provider integration translates its runtime, while the environment server owns product policy and access. The authoritative composition is in server.ts and serverRuntimeStartup.ts.