fix(mobile): block incompatible server connections

apps/mobile/src/features/connection/ConnectionStatusDot.tsx

@@ -35,6 +35,7 @@ function statusDotTone(state: ConnectionStatusDotState): {
         haloColor: "rgba(245,158,11,0.5)",
       };
     case "offline":
+    case "unsupported":
     case "error":
       return {
         dotColor: "#ef4444",

apps/mobile/src/features/connection/EnvironmentConnectionNotice.tsx

@@ -16,6 +16,8 @@ function noticeTitle(phase: EnvironmentConnectionPhase, environmentLabel: string
       return `Connecting to ${environmentLabel}...`;
     case "reconnecting":
       return `Reconnecting to ${environmentLabel}...`;
+    case "unsupported":
+      return "Client not supported";
     case "error":
       return `${environmentLabel} is unavailable`;
     case "available":
@@ -31,7 +33,7 @@ function noticeDetail(
   error: string | null,
 ): string {
   if (error) {
-    return `The app will keep retrying automatically. ${error}`;
+    return phase === "reconnecting" ? `The app will keep retrying automatically. ${error}` : error;
   }
 
   switch (phase) {
@@ -40,6 +42,8 @@ function noticeDetail(
     case "connecting":
     case "reconnecting":
       return `The ${resourceName} will load as soon as the environment is ready.`;
+    case "unsupported":
+      return "Use compatible versions of the app and server to connect.";
     case "available":
     case "error":
       return `Reconnect the environment to load the ${resourceName}.`;
@@ -95,7 +99,7 @@ export function EnvironmentConnectionNotice(props: {
           ) : null}
         </Text>
 
-        {props.connection.phase !== "offline" ? (
+        {props.connection.phase !== "offline" && props.connection.phase !== "unsupported" ? (
           <Pressable
             accessibilityRole="button"
             className="mt-1 rounded-full bg-subtle px-4 py-2.5 active:opacity-70"

apps/mobile/src/features/connection/connectionTone.ts

@@ -21,6 +21,12 @@ export function connectionTone(state: RemoteClientConnectionState): StatusTone {
         pillClassName: "bg-primary/10",
         textClassName: "text-foreground-secondary",
       };
+    case "unsupported":
+      return {
+        label: "Client not supported",
+        pillClassName: "bg-danger",
+        textClassName: "text-danger-foreground",
+      };
     case "error":
       return {
         label: "Connection failed",

apps/mobile/src/features/home/HomeScreen.tsx

@@ -169,11 +169,15 @@ function deriveEmptyState(props: {
   if (
     (catalogState.connectionState === "available" ||
       catalogState.connectionState === "offline" ||
-      catalogState.connectionState === "error") &&
+      catalogState.connectionState === "error" ||
+      catalogState.connectionState === "unsupported") &&
     !catalogState.hasLoadedShellSnapshot
   ) {
     return {
-      title: "Environment unavailable",
+      title:
+        catalogState.connectionState === "unsupported"
+          ? "Client not supported"
+          : "Environment unavailable",
       detail:
         catalogState.connectionError ??
         "The saved environment is offline. Check the URL or start the environment, then retry.",

apps/mobile/src/features/threads/floating-working-status.ts

@@ -51,6 +51,8 @@ export function connectionFloatingStatus(input: {
       };
     case "offline":
       return unavailable("You are offline");
+    case "unsupported":
+      return unavailable("Client not supported");
     case "error":
       return unavailable(
         input.connectionError

apps/mobile/src/state/asset-url-state.ts

@@ -21,7 +21,8 @@ export function deriveAssetUrlState(input: {
   if (
     input.connectionPhase === "offline" ||
     input.connectionPhase === "reconnecting" ||
-    input.connectionPhase === "error"
+    input.connectionPhase === "error" ||
+    input.connectionPhase === "unsupported"
   ) {
     return { _tag: "Failure", reason: "disconnected" };
   }

apps/mobile/src/state/workspaceModel.ts

@@ -65,6 +65,9 @@ function overallConnectionState(
   if (environments.some((environment) => environment.connectionState === "connecting")) {
     return "connecting";
   }
+  if (environments.some((environment) => environment.connectionState === "unsupported")) {
+    return "unsupported";
+  }
   if (environments.some((environment) => environment.connectionState === "error")) {
     return "error";
   }

apps/server/src/environment/ServerEnvironment.test.ts

@@ -1,4 +1,5 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
+import { ORCHESTRATION_PROTOCOL_VERSION } from "@t3tools/contracts";
 import { expect, it } from "@effect/vitest";
 import * as Crypto from "effect/Crypto";
 import * as Deferred from "effect/Deferred";
@@ -163,6 +164,7 @@ it.layer(NodeServices.layer)("ServerEnvironmentLive", (it) => {
       }).pipe(Effect.provide(makeServerEnvironmentLayer(baseDir)));
 
       expect(first.environmentId).toBe(second.environmentId);
+      expect(first.orchestrationProtocolVersion).toBe(ORCHESTRATION_PROTOCOL_VERSION);
       expect(second.capabilities.repositoryIdentity).toBe(true);
       expect(second.capabilities.connectionProbe).toBe(true);
       expect(second.capabilities.attachmentUploads).toBe(true);

apps/server/src/environment/ServerEnvironment.ts

@@ -1,5 +1,6 @@
 import {
   EnvironmentId,
+  ORCHESTRATION_PROTOCOL_VERSION,
   PROVIDER_SEND_TURN_MAX_FILE_BYTES,
   type ExecutionEnvironmentDescriptor,
 } from "@t3tools/contracts";
@@ -212,6 +213,7 @@ export const make = Effect.gen(function* () {
       ...(machine === null ? {} : { machine }),
     },
     serverVersion: packageJson.version,
+    orchestrationProtocolVersion: ORCHESTRATION_PROTOCOL_VERSION,
     capabilities: {
       repositoryIdentity: true,
       connectionProbe: true,

apps/web/src/components/ConnectionStatusDot.tsx

@@ -11,6 +11,7 @@ export function connectionPhaseDotClassName(phase: EnvironmentConnectionPhase):
     case "connecting":
     case "reconnecting":
       return "bg-warning";
+    case "unsupported":
     case "error":
       return "bg-destructive";
     default:

apps/web/src/components/ProviderUpdateLaunchNotification.environments.ts

@@ -29,6 +29,7 @@ function normalizeConnectionState(phase: string | undefined): EnvironmentUpdateC
     case "connecting":
     case "reconnecting":
       return "connecting";
+    case "unsupported":
     case "error":
       return "error";
     case "offline":

apps/web/src/components/cloud/cloudEnvironmentConnectionPresentation.ts

@@ -36,9 +36,11 @@ export function presentSavedCloudEnvironmentConnection(
         statusText: connectionStatusText(connection),
         tone: "connecting",
       };
+    case "unsupported":
     case "error":
       return {
-        buttonLabel: "Connection failed",
+        buttonLabel:
+          connection.phase === "unsupported" ? "Client not supported" : "Connection failed",
         statusText: connectionStatusText(connection),
         tone: "error",
       };

apps/web/src/components/settings/ConnectionsSettings.tsx

@@ -1456,6 +1456,8 @@ function savedBackendStatus(environment: EnvironmentPresentation): {
         text: connection.error ? `Reconnecting: ${connection.error}` : "Reconnecting",
         tone: "error",
       };
+    case "unsupported":
+      return { text: "Client not supported", tone: "error" };
     case "error":
       return {
         text: connection.error ? `Connection failed: ${connection.error}` : "Connection failed",

packages/client-runtime/src/connection/compatibility.test.ts

@@ -0,0 +1,54 @@
+import {
+  EnvironmentId,
+  ORCHESTRATION_PROTOCOL_VERSION,
+  type ExecutionEnvironmentDescriptor,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  appendOrchestrationProtocol,
+  orchestrationProtocolCompatibilityError,
+} from "./compatibility.ts";
+
+const descriptor = (orchestrationProtocolVersion?: number): ExecutionEnvironmentDescriptor => ({
+  environmentId: EnvironmentId.make("environment-remote"),
+  label: "Build Mac",
+  platform: { os: "darwin", arch: "arm64" },
+  serverVersion: "9.0.0",
+  ...(orchestrationProtocolVersion === undefined ? {} : { orchestrationProtocolVersion }),
+  capabilities: { repositoryIdentity: true },
+});
+
+describe("orchestration protocol compatibility", () => {
+  it("accepts the current protocol and announces it without disturbing socket credentials", () => {
+    expect(
+      orchestrationProtocolCompatibilityError(descriptor(ORCHESTRATION_PROTOCOL_VERSION)),
+    ).toBeNull();
+
+    const socketUrl = new URL(
+      appendOrchestrationProtocol("wss://host.test/ws?wsTicket=secret&connectionMethod=relay"),
+    );
+    expect(socketUrl.searchParams.get("orchestrationProtocol")).toBe(
+      String(ORCHESTRATION_PROTOCOL_VERSION),
+    );
+    expect(socketUrl.searchParams.get("wsTicket")).toBe("secret");
+    expect(socketUrl.searchParams.get("connectionMethod")).toBe("relay");
+  });
+
+  it("treats missing metadata as protocol 1", () => {
+    const error = orchestrationProtocolCompatibilityError(descriptor());
+    if (Number(ORCHESTRATION_PROTOCOL_VERSION) === 1) {
+      expect(error).toBeNull();
+    } else {
+      expect(error).toMatchObject({ reason: "unsupported" });
+    }
+  });
+
+  it("blocks a different protocol before connecting", () => {
+    const error = orchestrationProtocolCompatibilityError(
+      descriptor(ORCHESTRATION_PROTOCOL_VERSION + 1),
+    );
+    expect(error).toMatchObject({ reason: "unsupported" });
+    expect(error?.message).toContain("This client is not supported");
+  });
+});

packages/client-runtime/src/connection/compatibility.ts

@@ -0,0 +1,30 @@
+import {
+  ORCHESTRATION_PROTOCOL_QUERY_PARAM,
+  ORCHESTRATION_PROTOCOL_VERSION,
+  type ExecutionEnvironmentDescriptor,
+} from "@t3tools/contracts";
+
+import { ConnectionBlockedError } from "./model.ts";
+
+export function orchestrationProtocolCompatibilityError(
+  descriptor: ExecutionEnvironmentDescriptor,
+): ConnectionBlockedError | null {
+  // Servers shipped before negotiation use the original wire protocol.
+  const serverProtocolVersion = descriptor.orchestrationProtocolVersion ?? 1;
+  if (serverProtocolVersion === ORCHESTRATION_PROTOCOL_VERSION) {
+    return null;
+  }
+  return new ConnectionBlockedError({
+    reason: "unsupported",
+    detail:
+      serverProtocolVersion > ORCHESTRATION_PROTOCOL_VERSION
+        ? `This client is not supported by this server. Update your app or use a compatible release to connect to ${descriptor.label}.`
+        : `This client requires a newer server. Update T3 Code on ${descriptor.label} to connect.`,
+  });
+}
+
+export function appendOrchestrationProtocol(socketUrl: string): string {
+  const url = new URL(socketUrl);
+  url.searchParams.set(ORCHESTRATION_PROTOCOL_QUERY_PARAM, String(ORCHESTRATION_PROTOCOL_VERSION));
+  return url.toString();
+}

packages/client-runtime/src/connection/presentation.test.ts

@@ -5,6 +5,7 @@ import * as Option from "effect/Option";
 import { BearerConnectionProfile, type ConnectionCatalogEntry } from "./catalog.ts";
 import {
   BearerConnectionTarget,
+  ConnectionBlockedError,
   ConnectionTransientError,
   type SupervisorConnectionState,
 } from "./model.ts";
@@ -51,6 +52,21 @@ function supervisorState(overrides: Partial<SupervisorConnectionState>): Supervi
 }
 
 describe("connection presentation", () => {
+  it("labels a blocked protocol as unsupported", () => {
+    const connection = presentConnectionState(
+      supervisorState({
+        phase: "blocked",
+        lastFailure: new ConnectionBlockedError({
+          reason: "unsupported",
+          detail: "Update your app.",
+        }),
+      }),
+    );
+    expect(connection.phase).toBe("unsupported");
+    expect(connection.error).toBe("Update your app.");
+    expect(connectionStatusText(connection)).toBe("Client not supported");
+  });
+
   it("preserves profile display information without exposing credentials", () => {
     expect(connectionCatalogDisplayUrl(ENTRY)).toBe("https://environment.example.test");
   });

packages/client-runtime/src/connection/presentation.ts

@@ -10,7 +10,8 @@ export type EnvironmentConnectionPhase =
   | "connecting"
   | "reconnecting"
   | "connected"
-  | "error";
+  | "error"
+  | "unsupported";
 
 export interface EnvironmentConnectionPresentation {
   readonly phase: EnvironmentConnectionPhase;
@@ -48,7 +49,7 @@ export function presentConnectionState(
       };
     case "blocked":
       return {
-        phase: "error",
+        phase: state.lastFailure?.reason === "unsupported" ? "unsupported" : "error",
         error: state.lastFailure?.message ?? null,
         traceId: state.lastFailure?.traceId ?? null,
       };
@@ -69,6 +70,8 @@ export function connectionStatusText(connection: EnvironmentConnectionPresentati
         : "Reconnecting...";
     case "connected":
       return "Connected";
+    case "unsupported":
+      return "Client not supported";
     case "error":
       return connection.error
         ? `Connection failed. Reason: ${connection.error}`