Terminals, files, previews, MCP, VCS, and pull requests

Chat is the control surface, not the whole application. A running T3 environment also owns processes, workspace paths, Git state, provider credentials, and source- control integrations. The book has already traced turn orchestration, worktree creation, context, and checkpoints. This chapter follows the adjacent workbench services without retelling those internal sagas.

The rule that prevents most incorrect diagrams is simple: a visible panel does not move authority into the client. In the pinned implementation, server services keep the filesystem, PTY, VCS, asset-signing, and remote-host integrations. Web, desktop, and mobile clients ask one selected environment for a capability and render the result through surface-specific code.

1. The service map: owner before UI

flowchart LR
  C[Web / desktop / mobile client] -->|authenticated RPC| S[Environment server services]
  S -->|snapshot + live events| T[Server PTY]
  S -->|signed URL| A[Asset HTTP route]
  S -->|authenticated diff request| D[PR diff HTTP route]
  S -->|preview metadata| C
  C -. curated desktop IPC .-> E[Electron main PreviewManager]
  E --> W[Guest Chromium WebContents]
  P[Provider session] -->|scoped bearer HTTP| M[T3 MCP preview toolkit]
  M --> B[Preview automation broker]
  B -. compatible host lease .-> E

The lab’s surface rows intentionally say which edge is evidenced, not which feature is “supported” in the abstract. Desktop often shares the web renderer, but its Electron main/preload boundary adds authority that a hosted browser does not receive. Conversely, mobile has its own native terminal and file paths even though the server protocol is shared.

2. A terminal is a server process with a streamed screen

The terminal contract names a thread and a client-chosen terminal id; it carries a cwd, optional worktree path, dimensions, and bounded environment overrides. The server manager opens/reuses a PTY session, exposes lifecycle commands (open, write, resize, clear, restart, close), and offers two different subscriptions:

• attachStream begins with the selected terminal’s snapshot and follows it with output/lifecycle events. This is the high-fidelity path used to reconstruct a visible screen.
• metadata subscription is a cheaper stream of terminal summaries for a broader shell/session view.

  const attachStream: TerminalManager["Service"]["attachStream"] = (input, listener) => {
    let unsubscribe: (() => void) | null = null;
 
    return Effect.gen(function* () {
      const bufferedEvents: TerminalEvent[] = [];
      let deliverLive = false;
 
      unsubscribe = yield* subscribe((event) => {
        if (event.threadId !== input.threadId || event.terminalId !== input.terminalId) {
          return Effect.void;
        }
 
        if (!deliverLive) {
          bufferedEvents.push(event);
          return Effect.void;
        }
 
        const attachEvent = terminalEventToAttachEvent(event);
        return attachEvent ? listener(attachEvent) : Effect.void;
      });
 
      const initialSnapshot = yield* openOrAttachForStream(input);
 
      yield* listener({
        type: "snapshot",
        snapshot: initialSnapshot,
      });
 
      for (const event of bufferedEvents) {
        if (isDuplicateAttachSnapshotEvent(event, initialSnapshot)) {
          continue;
        }
 
        const attachEvent = terminalEventToAttachEvent(event);
        if (attachEvent) {
          yield* listener(attachEvent);
        }
      }
 
      deliverLive = true;
      return () => {
        unsubscribe?.();
        unsubscribe = null;
      };
    }).pipe(
      Effect.catchCause((cause) =>
        Effect.flatMap(
          Effect.sync(() => {
            unsubscribe?.();
            unsubscribe = null;
          }),
          () => Effect.failCause(cause),

Terminal history is maintained in memory, persisted with a debounce/cap, and then replayed on a later first open before a new process is started. That makes a reopened screen useful after a client disconnect; it does not turn terminal history into a durable replay of every process state or side effect. The manager’s finalizer kills its sessions, and thread deletion performs best-effort terminal and provider cleanup. Treat a terminal as a live server resource with an inspectable text history, not as a durable orchestration event stream.

Web renders that stream through its Ghostty-based surface. Mobile drives the same open/attach/write/resize/close protocol but renders through its native terminal module; it also explicitly reopens a stale, ended subscription only when the panel is shown. Desktop uses the web renderer path for the terminal panel. Those are rendering differences around one server-owned PTY boundary.

3. Files and assets are deliberately different paths

Workspace files use authenticated project operations: list/search entries, read a file, and write a file. The web file browser, preview, and editor are therefore views of an environment’s workspace service; they are not a sync engine that copies the project into the client. Mobile has a tree/file-preview path and obtains a workspace-file asset URL using the same thread/environment address.

An asset request is narrower. Its resource union names a workspace file in a thread, an attachment, or a project favicon. The server resolves the workspace context, normalizes the root, rejects paths outside that root, restricts previewable workspace resource types, resolves real paths, and emits an expiring signed URL. On retrieval it verifies the signature and expiry again; workspace claims also enforce exact-name or constrained relative-path rules, extension allow-lists, and canonical containment.

          cause,
        }),
    ),
  );
  if (claims.kind === "project-favicon" || claims.kind === "project-favicon-external") {
    const issuedAt = yield* Clock.currentTimeMillis;
    expiresAt =
      (Math.floor(issuedAt / PROJECT_FAVICON_TOKEN_BUCKET_MS) + 2) *
      PROJECT_FAVICON_TOKEN_BUCKET_MS;
    claims = { ...claims, expiresAt };
  }
  const encodedPayload = base64UrlEncode(encodeAssetClaims(claims));
  const token = `${encodedPayload}.${signPayload(encodedPayload, signingSecret)}`;
  return {
    relativeUrl: `${ASSET_ROUTE_PREFIX}/${token}/${encodeURIComponent(fileName)}`,
    expiresAt,
    ...(sourcePath !== undefined ? { sourcePath } : {}),
  };
});
 
export const resolveAsset = Effect.fn("AssetAccess.resolveAsset")(function* (
  token: string,
  relativePath: string,
) {
  const [encodedPayload, signature] = token.split(".");
  if (!encodedPayload || !signature) return null;
 
  const secretStore = yield* ServerSecretStore.ServerSecretStore;
  const signingSecret = yield* secretStore.getOrCreateRandom(SIGNING_SECRET_NAME, 32).pipe(
    Effect.tapError((cause) => Effect.logError("Failed to load the asset signing key.", { cause })),
    Effect.orElseSucceed(() => null),
  );
  if (!signingSecret) return null;
  if (!timingSafeEqualBase64Url(signature, signPayload(encodedPayload, signingSecret))) return null;
 
  const claims = decodeClaims(encodedPayload);
  if (!claims || claims.expiresAt <= (yield* Clock.currentTimeMillis)) return null;
 
  if (claims.kind === "attachment") {
    const config = yield* ServerConfig.ServerConfig;
    const attachmentPath = resolveAttachmentPathById({
      attachmentsDir: config.attachmentsDir,

This split also explains why “file preview” has more than one meaning. Source text can arrive by a project read operation; an image, browser document, or nested asset can arrive through a signed HTTP path; and the interactive application preview in the next section is neither of those things.

4. Preview state streams; Chromium authority stays on desktop

The server PreviewManager holds small per-thread/tab snapshots: URL/navigation state, history affordances, viewport setting, timestamps, a server epoch, and a monotonic revision. It serializes state mutation and publishes ordered lightweight events, so reconnecting clients can list metadata and converge on a tab’s recorded state. The manager’s refresh operation only confirms that a session exists; the actual reload is performed by the desktop bridge and later reported back.

The actual in-app browser is intentionally desktop-only. The Electron preload exposes a curated preview IPC API for tab creation, navigation, zoom, screenshot, recording, element picking, and automation actions. The web route rejects the preview keybinding outside a supported desktop runtime with a “Preview is desktop-only” message. Thus the server can coordinate preview metadata across subscribers, but it cannot make a plain web client or phone into a Chromium webview host.

This is a useful two-layer model:

1. Server coordination: tab identity, state/revision, and typed preview RPC.
2. Desktop enactment: the renderer requests actions through curated preload IPC; Electron main’s preview manager validates and owns the guest Chromium WebContents, then reports navigation, loading, and failures over the bridge.

That division prevents a remote client from assuming it can inspect a page merely because a server has a preview record. A record may exist while no compatible desktop host is connected.

5. T3’s MCP service gives a provider a scoped preview toolkit

T3 can attach its own t3-code MCP server to a provider session when the agent browser-access setting permits it. This is not the same as discovering or managing every external MCP server configured by Codex, Claude, Cursor, Grok, or OpenCode. It is a narrowly scoped T3 endpoint for preview operations.

At provider-session preparation, the server either revokes/clears prior MCP state when access is disabled or issues a fresh random bearer credential. Its scope is bound to the environment, thread, provider instance, and a registry-generated MCP session id—the latter is not an adapter-native Codex, Claude, Cursor, Grok, or OpenCode session identity. The registry stores a hash, not the raw token, and only advertises the preview capability. The /mcp route sits outside ordinary environment auth, so it requires that provider-scoped bearer credential. Registry liveness is refreshed by both MCP traffic and active provider turns; stop/revoke paths remove credentials eagerly, while abandoned records age out after the liveness window.

    const next = new Map(
      Array.from(records).filter(
        ([, record]) => timestamp - record.lastAliveAt <= livenessWindowMs,
      ),
    );
    return next.size === records.size ? records : next;
  };
 
  const issue: McpSessionRegistryShape["issue"] = Effect.fn("McpSessionRegistry.issue")(
    function* (request) {
      const issuedAt = yield* currentTimeMillis;
      const providerSessionId = yield* crypto.randomUUIDv4.pipe(Effect.orDie);
      const rawToken = yield* crypto.randomBytes(32).pipe(Effect.map(tokenFromBytes), Effect.orDie);
      const tokenHash = yield* hashToken(rawToken);
      const scope: McpInvocationContext.McpInvocationScope = {
        environmentId,
        threadId: ThreadId.make(request.threadId),
        providerSessionId,
        providerInstanceId: ProviderInstanceId.make(request.providerInstanceId),
        capabilities: new Set(["preview"]),
        issuedAt,
      };
      yield* SynchronizedRef.update(state, ({ records }) => {
        const next = new Map(pruneDead(records, issuedAt));
        next.set(tokenHash, { tokenHash, scope, lastAliveAt: issuedAt });
        return { records: next };
      });
      return {
        config: {
          environmentId,
          threadId: scope.threadId,
          providerSessionId,
          providerInstanceId: scope.providerInstanceId,
          endpoint,
          authorizationHeader: `Bearer ${rawToken}`,
        },
      };
    },
  );
 
  const resolve: McpSessionRegistryShape["resolve"] = Effect.fn("McpSessionRegistry.resolve")(
    function* (rawToken) {
      if (rawToken.length === 0) return undefined;
      const tokenHash = yield* hashToken(rawToken);
      const timestamp = yield* currentTimeMillis;
      return yield* SynchronizedRef.modify(state, ({ records }) => {
        const current = pruneDead(records, timestamp);
        const record = current.get(tokenHash);
        if (!record) return [undefined, { records: current }] as const;
        const next = new Map(current);
        next.set(tokenHash, { ...record, lastAliveAt: timestamp });
        return [record.scope, { records: next }] as const;
      });
    },
  );
 
  const touch: McpSessionRegistryShape["touch"] = Effect.fn("McpSessionRegistry.touch")(

All five adapter paths can consume the T3-owned MCP configuration, but their native injection mechanisms differ: Codex uses app-server arguments plus a bearer-token environment variable; Claude supplies an HTTP MCP server; Cursor and Grok pass ACP MCP server definitions; OpenCode registers the remote server only when T3 owns the local OpenCode server (!server.external). This is adapter integration for one T3 toolkit, not shared management of each harness’s external MCP inventory.

The MCP server authenticates the request, provides the resulting invocation scope to preview toolkit handlers, and sends automation through PreviewAutomationBroker. The broker selects a compatible desktop host in the same environment, keeps a provider-session-to-host lease while the connection remains live, and returns an unavailable error when no suitable host can perform an operation. It does not silently transfer an active browser automation session to another desktop because a credential timer expired.

6. VCS remains an environment service; worktrees remain a lifecycle saga

The VCS contract exposes a driver kind and capability flags such as worktree, bookmark, atomic-snapshot, and default-push support. Client views query or command the server driver against the selected workspace; they do not obtain raw local Git access merely by rendering a branch, diff, or worktree picker.

Two earlier boundaries matter here:

• Chapter 22 traces the start-turn worktree saga, including its server filesystem effects and failure seam.
• Chapter 27 traces hidden checkpoint refs, comparison modes, and the destructive restore/revert path.

The workbench is where those results become visible: a terminal’s cwd can be the thread worktree, a file panel reads it, and review/VCS panels query its Git state. That co-location is not a transaction. A terminal command, a Git operation, and a provider file edit still have their own ordering and error channels.

7. Pull requests add host authorization and a second transport lane

For each eligible project with a repository identity and supported host provider, the pull-request service builds a repository target. Projects without the required identity/provider/repository are skipped. It deduplicates worktrees of one repository for listing purposes, but retains alternate roots for host-viewer lookup so one unreadable checkout does not make a whole host look signed out. Host support and account identity are therefore server-side facts, not client guesses.

For a write, the service checks two distinct gates in order:

1. Host/provider capability: does the selected provider support this action, merge strategy, update strategy, comment/review feature, or other requested operation?
2. Fresh viewer permission: does the currently signed-in account have the necessary host-reported right now?

Only then does it call the host provider. The server deliberately does not try to invent permissions it cannot query, such as whether a person may edit their own already-posted text; that decision stays with the host. Successful mutations bump server-side invalidation epochs so subsequent list/detail reads refresh rather than pretend cached rows are authoritative.

  const runAction: PullRequestService["Service"]["runAction"] = (input) =>
    requireProject(input).pipe(
      Effect.flatMap((project): Effect.Effect<void, PullRequestError> => {
        // The surface hides what a host cannot do, and this refuses it as well: a request that
        // reached here anyway must not be handed to a provider that never claimed the action.
        if (!project.api.capabilities.actions.includes(input.action)) {
          return Effect.fail(
            new PullRequestOperationError({
              operation: "runAction",
              detail: `This host cannot ${input.action} a change request.`,
            }),
          );
        }
        // A strategy the host does not offer must be refused rather than passed on: every
        // provider maps an unrecognised method to its own default, so asking Azure DevOps to
        // rebase would quietly merge instead of failing.
        if (
          input.mergeMethod !== undefined &&
          !project.api.capabilities.mergeMethods.includes(input.mergeMethod)
        ) {
          return Effect.fail(
            new PullRequestOperationError({
              operation: "runAction",
              detail: `This host cannot merge with the ${input.mergeMethod} strategy.`,
            }),
          );
        }
        // The same for the way a stale branch is brought up to date: a host that only merges
        // must not be asked to rebase and left to pick something else.
        if (
          input.updateMethod !== undefined &&
          !(project.api.capabilities.updateMethods ?? []).includes(input.updateMethod)
        ) {
          return Effect.fail(
            new PullRequestOperationError({
              operation: "runAction",
              detail: `This host cannot update a branch by ${input.updateMethod}.`,
            }),
          );
        }
        // What the host can do and what this account may ask of it are two questions, and both
        // have to say yes. The second is asked last, because it costs a request and the checks
        // above do not.
        return viewerPermissionsOf(project, input, "runAction").pipe(
          Effect.flatMap((viewer): Effect.Effect<void, PullRequestError> => {
            if (!viewer.actions.includes(input.action)) {
              return Effect.fail(
                new PullRequestOperationError({
                  operation: "runAction",
                  detail: ACTION_ACCESS_REFUSALS[input.action],
                }),
              );
            }
            if (
              input.updateMethod !== undefined &&
              !(viewer.updateMethods ?? []).includes(input.updateMethod)
            ) {
              return Effect.fail(
                new PullRequestOperationError({
                  operation: "runAction",
                  detail: ACTION_ACCESS_REFUSALS["update-branch"],
                }),
              );
            }
            return project.api
              .runAction({
                cwd: project.project.workspaceRoot,
                repository: project.repository,

Most PR controls use typed RPC. Diff content is exceptional: large, compressible diff slices travel through an authenticated HTTP endpoint, with a host-opaque cursor and truncation/next-cursor fields. The web route checks each connected environment’s advertised pull-request capability and selects a capable source. Desktop inherits that web route. This pinned mobile source audit found terminal, file, and VCS paths (including a control that can open an existing PR externally), but no corresponding in-app pull-request list/detail route; that observation is not a promise about a future mobile release.

What a surface can honestly claim

The durable lesson is to locate authority before adding an arrow: environment server for resources and host integrations, desktop for browser enactment, provider adapter/session for harness-native behavior, and client for the interactive view of a selected environment.