tui review

README.md

@@ -55,6 +55,31 @@ brew install --cask t3-code
 yay -S t3code-bin
 ```
 
+### Terminal UI (over SSH, no port forwarding)
+
+If you run a T3 Code server on a remote machine, you can monitor and drive its
+threads from a terminal UI that talks to the already-running local server — no
+port forwarding required. The TUI renders with [OpenTUI](https://opentui.com)
+and runs on [Bun](https://bun.sh), so install Bun on the box first:
+
+```bash
+ssh my-remote-box
+curl -fsSL https://bun.sh/install | bash   # if Bun isn't already installed
+t3 tui                                      # or: npx t3@latest tui
+```
+
+`t3 tui` (Node) bootstraps auth and launches the UI in a Bun subprocess; if Bun
+isn't on `PATH` it prints an install hint and exits.
+
+The prompt is always ready: pick a thread with `↑`/`↓` and just start typing,
+then press `Enter` to send. Conversations render as Markdown and follow the
+latest reply; scroll with `PgUp`/`PgDn`. The TUI also lets you approve/deny tool
+prompts (`^A`/`^R`), interrupt a running turn (`^G`), start new threads (`^N`),
+and attach to a thread's terminal (`^E`; `Ctrl-Q` detaches). Start a server
+first with `t3 serve` if one isn't already running. Long conversations stay
+responsive by showing a bounded page; use the earlier/newer rows to move through
+older history.
+
 ## Some notes
 
 We are very very early in this project. Expect bugs.

apps/server/package.json

@@ -29,9 +29,11 @@
     "@effect/sql-sqlite-bun": "catalog:",
     "@ff-labs/fff-node": "0.9.4",
     "@opencode-ai/sdk": "^1.3.15",
+    "@opentui/core": "^0.4.1",
     "@pierre/diffs": "catalog:",
     "effect": "catalog:",
     "node-pty": "^1.1.0",
+    "sharp": "^0.34.5",
     "yaml": "catalog:"
   },
   "devDependencies": {

apps/server/scripts/cli.ts

@@ -27,7 +27,9 @@ import {
   ServerCliDevelopmentIconTargetMissingError,
   ServerCliPublishIconSourceMissingError,
   ServerCliPublishIconTargetMissingError,
+  ServerCliTuiBundleImportError,
 } from "./cliErrors.ts";
+import { findUnresolvedTuiBundleImport } from "./tuiBundle.ts";
 
 interface PackageJson {
   name: string;
@@ -162,6 +164,23 @@ const buildCmd = Command.make(
         }),
       );
 
+      const tuiEntry = path.join(repoRoot, "apps/tui/dist/index.js");
+      const tuiTarget = path.join(serverDir, "dist/tui/index.js");
+      if (!(yield* fs.exists(tuiEntry))) {
+        return yield* new ServerCliBuildAssetMissingError({ assetPath: tuiEntry });
+      }
+      yield* fs.makeDirectory(path.dirname(tuiTarget), { recursive: true });
+      yield* fs.copyFile(tuiEntry, tuiTarget);
+      const tuiBundle = yield* fs.readFileString(tuiTarget);
+      const unresolvedImport = findUnresolvedTuiBundleImport(tuiBundle);
+      if (unresolvedImport !== null) {
+        return yield* new ServerCliTuiBundleImportError({
+          assetPath: tuiTarget,
+          specifier: unresolvedImport,
+        });
+      }
+      yield* Effect.log("[cli] Bundled TUI entry into dist/tui");
+
       const webDist = path.join(repoRoot, "apps/web/dist");
       const clientTarget = path.join(serverDir, "dist/client");
 
@@ -223,7 +242,7 @@ const publishCmd = Command.make(
       const packageJsonPath = path.join(serverDir, "package.json");
 
       // Assert build assets exist
-      for (const relPath of ["dist/bin.mjs", "dist/client/index.html"]) {
+      for (const relPath of ["dist/bin.mjs", "dist/client/index.html", "dist/tui/index.js"]) {
         const abs = path.join(serverDir, relPath);
         if (!(yield* fs.exists(abs))) {
           return yield* new ServerCliBuildAssetMissingError({ assetPath: abs });

apps/server/scripts/cliErrors.test.ts

@@ -1,6 +1,10 @@
 import { assert, describe, it } from "@effect/vitest";
 
-import { ServerCliBuildAssetMissingError, ServerCliCommandExitError } from "./cliErrors.ts";
+import {
+  ServerCliBuildAssetMissingError,
+  ServerCliCommandExitError,
+  ServerCliTuiBundleImportError,
+} from "./cliErrors.ts";
 
 describe("server CLI errors", () => {
   it("preserves failed command context without changing its message", () => {
@@ -28,4 +32,16 @@ describe("server CLI errors", () => {
       "Missing build asset: /repo/server.mjs. Run the build subcommand first.",
     );
   });
+
+  it("identifies an unresolved TUI runtime import", () => {
+    const error = new ServerCliTuiBundleImportError({
+      assetPath: "/repo/dist/tui/index.js",
+      specifier: "@xterm/headless",
+    });
+
+    assert.equal(
+      error.message,
+      "TUI bundle contains an unresolved runtime import (@xterm/headless): /repo/dist/tui/index.js",
+    );
+  });
 });

apps/server/scripts/cliErrors.ts

@@ -68,3 +68,15 @@ export class ServerCliBuildAssetMissingError extends Schema.TaggedErrorClass<Ser
     return `Missing build asset: ${this.assetPath}. Run the build subcommand first.`;
   }
 }
+
+export class ServerCliTuiBundleImportError extends Schema.TaggedErrorClass<ServerCliTuiBundleImportError>()(
+  "ServerCliTuiBundleImportError",
+  {
+    assetPath: Schema.String,
+    specifier: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `TUI bundle contains an unresolved runtime import (${this.specifier}): ${this.assetPath}`;
+  }
+}

apps/server/scripts/tuiBundle.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import { findUnresolvedTuiBundleImport } from "./tuiBundle.ts";
+
+describe("findUnresolvedTuiBundleImport", () => {
+  it("rejects private workspace imports left in the release bundle", () => {
+    expect(findUnresolvedTuiBundleImport('import { x } from "@t3tools/contracts";')).toBe(
+      "@t3tools/contracts",
+    );
+  });
+
+  it("rejects package lookups hidden behind createRequire", () => {
+    expect(
+      findUnresolvedTuiBundleImport(
+        'NodeModule.createRequire(import.meta.url)("@xterm/headless");',
+      ),
+    ).toBe("@xterm/headless");
+  });
+
+  it("allows explicit public and native runtime imports", () => {
+    expect(
+      findUnresolvedTuiBundleImport(
+        'import { createCliRenderer } from "@opentui/core";\nimport sharp from "sharp";',
+      ),
+    ).toBeNull();
+  });
+});

apps/server/scripts/tuiBundle.ts

@@ -0,0 +1,9 @@
+const PRIVATE_WORKSPACE_IMPORT = /(?:from\s+|import\(|require\()\s*["'](@t3tools\/[^"']+)["']/u;
+const OPAQUE_PACKAGE_REQUIRE = /createRequire\([^)]*\)\(\s*["']((?:@[^/"']+\/)?[^/"']+)["']\s*\)/u;
+
+/** Find a package lookup that Bun left unresolved in the staged TUI bundle. */
+export function findUnresolvedTuiBundleImport(source: string): string | null {
+  return (
+    source.match(PRIVATE_WORKSPACE_IMPORT)?.[1] ?? source.match(OPAQUE_PACKAGE_REQUIRE)?.[1] ?? null
+  );
+}

apps/server/src/auth/RpcAuthorization.ts

@@ -82,6 +82,7 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.terminalClear]: AuthTerminalOperateScope,
   [WS_METHODS.terminalRestart]: AuthTerminalOperateScope,
   [WS_METHODS.terminalClose]: AuthTerminalOperateScope,
+  [WS_METHODS.terminalList]: AuthTerminalOperateScope,
   [WS_METHODS.subscribeTerminalEvents]: AuthTerminalOperateScope,
   [WS_METHODS.subscribeTerminalMetadata]: AuthTerminalOperateScope,
   [WS_METHODS.previewOpen]: AuthOrchestrationOperateScope,

apps/server/src/bin.ts

@@ -15,6 +15,7 @@ import { sharedServerCommandFlags } from "./cli/config.ts";
 import { projectCommand } from "./cli/project.ts";
 import { runServerCommand, serveCommand, startCommand } from "./cli/server.ts";
 import { serviceCommand } from "./cli/service.ts";
+import { tuiCommand } from "./cli/tui.ts";
 
 const CliRuntimeLayer = Layer.mergeAll(NodeServices.layer, NetService.layer);
 
@@ -50,6 +51,7 @@ export const makeCli = ({ cloudEnabled = hasCloudPublicConfig } = {}) =>
       startCommand,
       serveCommand,
       pairCommand,
+      tuiCommand,
       authCommand,
       projectCommand,
       serviceCommand,

apps/server/src/checkpointing/CheckpointDiffQuery.test.ts

@@ -77,6 +77,8 @@ describe("CheckpointDiffQuery.layer", () => {
           Layer.succeed(ProjectionSnapshotQuery.ProjectionSnapshotQuery, {
             getCommandReadModel: () =>
               Effect.die("CheckpointDiffQuery should not request the command read model"),
+            getThreadActivitiesPage: () =>
+              Effect.die("CheckpointDiffQuery should not request thread activities"),
             getSnapshot: () =>
               Effect.die("CheckpointDiffQuery should not request the full orchestration snapshot"),
             getShellSnapshot: () =>
@@ -186,6 +188,8 @@ describe("CheckpointDiffQuery.layer", () => {
           Layer.succeed(ProjectionSnapshotQuery.ProjectionSnapshotQuery, {
             getCommandReadModel: () =>
               Effect.die("CheckpointDiffQuery should not request the command read model"),
+            getThreadActivitiesPage: () =>
+              Effect.die("CheckpointDiffQuery should not request thread activities"),
             getSnapshot: () =>
               Effect.die("CheckpointDiffQuery should not request the full orchestration snapshot"),
             getShellSnapshot: () =>
@@ -270,6 +274,8 @@ describe("CheckpointDiffQuery.layer", () => {
           Layer.succeed(ProjectionSnapshotQuery.ProjectionSnapshotQuery, {
             getCommandReadModel: () =>
               Effect.die("CheckpointDiffQuery should not request the command read model"),
+            getThreadActivitiesPage: () =>
+              Effect.die("CheckpointDiffQuery should not request thread activities"),
             getSnapshot: () =>
               Effect.die("CheckpointDiffQuery should not request the full orchestration snapshot"),
             getShellSnapshot: () =>
@@ -339,6 +345,8 @@ describe("CheckpointDiffQuery.layer", () => {
           Layer.succeed(ProjectionSnapshotQuery.ProjectionSnapshotQuery, {
             getCommandReadModel: () =>
               Effect.die("CheckpointDiffQuery should not request the command read model"),
+            getThreadActivitiesPage: () =>
+              Effect.die("CheckpointDiffQuery should not request thread activities"),
             getSnapshot: () =>
               Effect.die("CheckpointDiffQuery should not request the full orchestration snapshot"),
             getShellSnapshot: () =>
@@ -393,6 +401,8 @@ describe("CheckpointDiffQuery.layer", () => {
           Layer.succeed(ProjectionSnapshotQuery.ProjectionSnapshotQuery, {
             getCommandReadModel: () =>
               Effect.die("CheckpointDiffQuery should not request the command read model"),
+            getThreadActivitiesPage: () =>
+              Effect.die("CheckpointDiffQuery should not request thread activities"),
             getSnapshot: () =>
               Effect.die("CheckpointDiffQuery should not request the full orchestration snapshot"),
             getShellSnapshot: () =>

apps/server/src/cli/pair.ts

@@ -31,12 +31,7 @@ import * as Option from "effect/Option";
 import * as References from "effect/References";
 import * as Schema from "effect/Schema";
 import { Command, Flag, GlobalFlag } from "effect/unstable/cli";
-import {
-  FetchHttpClient,
-  HttpClient,
-  HttpClientRequest,
-  HttpClientResponse,
-} from "effect/unstable/http";
+import { FetchHttpClient } from "effect/unstable/http";
 
 import * as EnvironmentAuth from "../auth/EnvironmentAuth.ts";
 import * as ServerConfig from "../config.ts";
@@ -54,9 +49,12 @@ import {
   resolveHeadlessConnectionString,
 } from "../startupAccess.ts";
 import { baseDirFlag, DurationFromString } from "./config.ts";
+import {
+  type EnvironmentProbeResult,
+  isProcessAlive,
+  probeEnvironmentDescriptor,
+} from "./runningServer.ts";
 
-const WELL_KNOWN_ENVIRONMENT_PATH = "/.well-known/t3/environment";
-const PAIR_PROBE_TIMEOUT = Duration.millis(2_500);
 // Tailscale provisions an HTTPS certificate on the first request to a fresh
 // serve mapping, which can take a few seconds.
 const TAILSCALE_PROBE_ATTEMPTS = 5;
@@ -192,54 +190,6 @@ export const formatPairOutput = (input: {
     "",
   ].join("\n");
 
-/**
- * Three outcomes, because they drive different decisions: a T3 descriptor
- * (pair with it), nothing answering (safe to configure Tailscale Serve), or
- * something answering that is not a T3 server (do NOT overwrite its mapping).
- */
-type EnvironmentProbeResult =
-  | { readonly _tag: "descriptor"; readonly descriptor: ExecutionEnvironmentDescriptor }
-  | { readonly _tag: "unreachable" }
-  | { readonly _tag: "not-a-t3-server" };
-
-const probeEnvironmentDescriptor = (
-  baseUrl: string,
-): Effect.Effect<EnvironmentProbeResult, never, HttpClient.HttpClient> =>
-  Effect.gen(function* () {
-    const client = yield* HttpClient.HttpClient;
-    const request = HttpClientRequest.get(new URL(WELL_KNOWN_ENVIRONMENT_PATH, baseUrl).toString());
-    const response = yield* client.execute(request).pipe(
-      Effect.timeout(PAIR_PROBE_TIMEOUT),
-      // Transport failure or timeout: nothing (reachable) is listening there.
-      Effect.mapError(() => ({ _tag: "unreachable" }) as const),
-    );
-    // Bad-gateway family means a proxy (Tailscale Serve) answered for a
-    // backend that is gone — a stale mapping, not a live occupant. Treating
-    // it as unreachable lets `t3 pair --tailscale` repair its own mapping
-    // after the server's port changed.
-    if (response.status === 502 || response.status === 503 || response.status === 504) {
-      return { _tag: "unreachable" } as const;
-    }
-    // Anything else that answered HTTP but not with a valid descriptor is
-    // some other service.
-    const descriptor = yield* HttpClientResponse.filterStatusOk(response).pipe(
-      Effect.flatMap(HttpClientResponse.schemaBodyJson(ExecutionEnvironmentDescriptor)),
-      Effect.mapError(() => ({ _tag: "not-a-t3-server" }) as const),
-    );
-    return { _tag: "descriptor", descriptor } as const;
-  }).pipe(Effect.catch((outcome) => Effect.succeed(outcome)));
-
-// signal 0 delivers nothing; it only reports whether the pid exists. EPERM
-// means it exists but belongs to another user, which still counts as alive.
-const isProcessAlive = (pid: number): boolean => {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error instanceof Error && "code" in error && error.code === "EPERM";
-  }
-};
-
 interface DiscoveredPairTarget {
   readonly baseDir: string;
   readonly variant: PairStateVariant;

apps/server/src/cli/runningServer.test.ts

@@ -0,0 +1,73 @@
+// @effect-diagnostics nodeBuiltinImport:off - integration test owns a loopback HTTP server.
+import * as NodeHttp from "node:http";
+
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import { FetchHttpClient } from "effect/unstable/http";
+
+import type { PersistedServerRuntimeState } from "../serverRuntimeState.ts";
+import { isLivePersistedServerRuntimeState } from "./runningServer.ts";
+
+const descriptor = {
+  environmentId: "running-server-test",
+  label: "running-server-test",
+  platform: { os: "linux", arch: "x64" },
+  serverVersion: "0.0.1",
+  capabilities: { repositoryIdentity: true },
+};
+
+const state = (origin: string, pid = process.pid): PersistedServerRuntimeState => ({
+  version: 1,
+  pid,
+  port: Number(new URL(origin).port),
+  origin,
+  startedAt: "2026-08-01T00:00:00.000Z",
+});
+
+const withServer = <A, E, R>(run: (origin: string) => Effect.Effect<A, E, R>) =>
+  Effect.acquireUseRelease(
+    Effect.callback<NodeHttp.Server>((resume) => {
+      const server = NodeHttp.createServer((request, response) => {
+        if (request.url === "/.well-known/t3/environment") {
+          response.writeHead(200, { "content-type": "application/json" });
+          response.end(JSON.stringify(descriptor));
+          return;
+        }
+        response.writeHead(404);
+        response.end();
+      });
+      server.listen(0, "127.0.0.1", () => resume(Effect.succeed(server)));
+    }),
+    (server) => {
+      const address = server.address();
+      if (address === null || typeof address === "string") {
+        return Effect.die(new Error("Expected a TCP address"));
+      }
+      return run(`http://127.0.0.1:${String(address.port)}`);
+    },
+    (server) => Effect.sync(() => server.close()),
+  );
+
+describe("live persisted server validation", () => {
+  it.effect("accepts a live pid whose origin serves a T3 descriptor", () =>
+    withServer((origin) =>
+      Effect.gen(function* () {
+        assert.isTrue(yield* isLivePersistedServerRuntimeState(state(origin)));
+      }),
+    ).pipe(Effect.provide(FetchHttpClient.layer)),
+  );
+
+  it.effect("rejects a dead pid even when the origin was reused by T3", () =>
+    withServer((origin) =>
+      Effect.gen(function* () {
+        assert.isFalse(yield* isLivePersistedServerRuntimeState(state(origin, 4_194_305)));
+      }),
+    ).pipe(Effect.provide(FetchHttpClient.layer)),
+  );
+
+  it.effect("rejects a live pid when the recorded origin is unreachable", () =>
+    Effect.gen(function* () {
+      assert.isFalse(yield* isLivePersistedServerRuntimeState(state("http://127.0.0.1:1")));
+    }).pipe(Effect.provide(FetchHttpClient.layer)),
+  );
+});