@@ -6,8 +6,14 @@ import { afterEach, test } from "node:test";
 import {
   createClientRuntimeHostProfileCatalog,
   LOCAL_RUNTIME_HOST_PROFILE,
+  RuntimeHostRemoteCompatibilityError,
   type ResolvedRuntimeHostProfile,
 } from "@maka/runtime-host/client";
+import {
+  INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID,
+  RUNTIME_HOST_COMPATIBILITY_EPOCH,
+  RUNTIME_HOST_PROTOCOL_VERSION,
+} from "@maka/runtime-host/protocol";
 import {
   createDesktopRuntimeHostProfileService,
   resolveDesktopRuntimeHostStartup,
@@ -22,6 +28,13 @@ const PROFILE = {
   transport: { kind: "tls" as const, url: "wss://runtime.example.com" },
   rootId: ROOT_ID,
 };
+const READY_PROFILE = {
+  id: "backup",
+  name: "Backup",
+  kind: "remote" as const,
+  transport: { kind: "tls" as const, url: "wss://backup.example.com" },
+  rootId: "b".repeat(64),
+};
 const temporaryDirectories: string[] = [];
 
 afterEach(async () => {
@@ -217,6 +230,62 @@ test("preserves an enabled remote profile when that Host is unavailable", async
   assert.equal(result.snapshot.entries.find((entry) => entry.profile.id === "local")?.enabled, true);
 });
 
+test("projects a shared compatibility error through an unavailable enabled remote profile", async () => {
+  const root = await clientRoot();
+  const catalog = createClientRuntimeHostProfileCatalog(root);
+  await catalog.create(PROFILE, "office-token");
+  await catalog.create(READY_PROFILE, "backup-token");
+  const compatibilityError = new RuntimeHostRemoteCompatibilityError("office", {
+    kind: "incompatible",
+    hostEpoch: "host-epoch",
+    protocolMin: RUNTIME_HOST_PROTOCOL_VERSION + 1,
+    protocolMax: RUNTIME_HOST_PROTOCOL_VERSION + 2,
+    compatibilityEpoch: RUNTIME_HOST_COMPATIBILITY_EPOCH - 1,
+    compositionId: INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID,
+    compositionRevision: "host-revision",
+    state: "ready",
+    replacement: "blocked_by_residency",
+  });
+  const service = createDesktopRuntimeHostProfileService({
+    clientDataRoot: root,
+    startup: {
+      preferences: {
+        schemaVersion: 2,
+        defaultProfileId: LOCAL_RUNTIME_HOST_PROFILE.id,
+        enabledRemoteProfileIds: [PROFILE.id, READY_PROFILE.id],
+      },
+      remotes: [
+        { profile: PROFILE, credential: "office-token" },
+        { profile: READY_PROFILE, credential: "backup-token" },
+      ],
+      unavailable: new Map(),
+    },
+    states: () => [
+      connectingLocal(),
+      unavailable({ profile: PROFILE, credential: "office-token" }, compatibilityError),
+      ready({ profile: READY_PROFILE, credential: "backup-token" }),
+    ],
+    enable: async () => undefined,
+    disable: async () => undefined,
+    setDefault: () => undefined,
+    catalog,
+  });
+
+  const snapshot = await service.getSnapshot();
+  const office = snapshot.entries.find((entry) => entry.profile.id === PROFILE.id);
+  const backup = snapshot.entries.find((entry) => entry.profile.id === READY_PROFILE.id);
+  const local = snapshot.entries.find((entry) => entry.profile.id === LOCAL_RUNTIME_HOST_PROFILE.id);
+
+  assert.equal(office?.enabled, true);
+  assert.equal(office?.readiness, "unavailable");
+  assert.equal(office?.message, compatibilityError.message);
+  assert.equal(local?.enabled, true);
+  assert.equal(local?.readiness, "connecting");
+  assert.equal(backup?.enabled, true);
+  assert.equal(backup?.readiness, "ready");
+  assert.equal(backup?.message, undefined);
+});
+
 test("keeps enablement, default selection, and removal as separate states", async () => {
   const root = await clientRoot();
   await createClientRuntimeHostProfileCatalog(root).create(PROFILE, "token");
@@ -264,3 +333,26 @@ function connecting(target: ResolvedRuntimeHostProfile): RuntimeHostDesktopTarge
     readiness: "connecting",
   };
 }
+
+function ready(target: ResolvedRuntimeHostProfile): RuntimeHostDesktopTargetState {
+  return {
+    epoch: `epoch-${target.profile.id}`,
+    target,
+    readiness: "ready",
+    candidate: {
+      client: { hostId: target.profile.kind === "remote" ? target.profile.rootId : ROOT_ID },
+    } as never,
+  };
+}
+
+function unavailable(
+  target: ResolvedRuntimeHostProfile,
+  error: Error,
+): RuntimeHostDesktopTargetState {
+  return {
+    epoch: `epoch-${target.profile.id}`,
+    target,
+    readiness: "unavailable",
+    error,
+  };
+}
@@ -167,6 +167,14 @@ maka run --host office --project '<projectId>' "Summarize this project"
 
 Each TUI or CLI process connects to one Profile. TUI may interact with SSH during its initial connection; non-interactive commands require preconfigured authentication.
 
+## Compatibility troubleshooting
+
+`RUNTIME_HOST_REMOTE_INCOMPATIBLE` means the Client and remote Runtime Host cannot safely communicate. Compare the Client and Host compatibility epochs first. When the diagnostic reports them, also inspect the Client and Host protocol ranges and composition IDs (including the Host composition revision).
+
+Use compatible Client and Host builds. After updating the Host, the operator must restart its remote Runtime Host service, then retry the connection.
+
+Remote Clients never auto-upgrade or restart the Host, downgrade the transport, mutate the Profile, change the default Host or Session, or expose credentials, endpoints, paths, or State Roots in this diagnostic.
+
 ## Security boundaries
 
 - Do not put credentials on the command line or in Profile JSON.
 
@@ -161,6 +161,14 @@ maka run --host office --project '<projectId>' "总结这个项目"
 
 每个 TUI 或 CLI 进程只连接一个 Profile。TUI 的首次 SSH 连接可以交互；非交互命令要求提前配置认证。
 
+## 兼容性排查
+
+`RUNTIME_HOST_REMOTE_INCOMPATIBLE` 表示 Client 与远程 Runtime Host 无法安全通信。先比较 Client 与 Host 的 compatibility epoch；当诊断中提供相关信息时，也应检查 Client 和 Host 的 protocol range、composition ID，以及 Host 的 composition revision。
+
+请使用彼此兼容的 Client 和 Host build。更新 Host 后，由 Host 的 operator 重启远程 Runtime Host service，然后重试连接。
+
+Remote Client 不会自动升级或重启 Host、降级 transport、修改 Profile、默认 Host 或 Session，也不会在此诊断中暴露 credential、endpoint、path 或 State Root。
+
 ## 安全边界
 
 - 不要把 credential 放在命令行或 Profile JSON 中。
 
@@ -7,13 +7,19 @@ import { fileURLToPath } from 'node:url';
 import {
   connectRemoteRuntimeHostProfile,
   createClientRuntimeHostProfileCatalog,
+  RuntimeHostRemoteCompatibilityError,
   RuntimeHostStartupError,
   type RuntimeHostConnection,
+  type RuntimeHostProfileCatalog,
+  type RemoteRuntimeHostProfile,
 } from '@maka/runtime-host/client';
 import {
   INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID,
   RUNTIME_HOST_COMPATIBILITY_EPOCH,
+  RUNTIME_HOST_PROTOCOL_VERSION,
   RUNTIME_HOST_REGISTRATION_SCHEMA_VERSION,
+  type ClientSurface,
+  type HostIncompatible,
 } from '@maka/runtime-host/protocol';
 import {
   connectRuntimeHostCli,
@@ -310,6 +316,83 @@ test('remote CLI profile state and Client identity use the explicit Client Data
   await context.close();
 });
 
+test('CLI and TUI remote profiles preserve shared compatibility errors', async () => {
+  const cases: readonly {
+    readonly surface: Extract<ClientSurface, 'run' | 'tui'>;
+    readonly handshake: HostIncompatible;
+  }[] = [
+    {
+      surface: 'run',
+      handshake: incompatibleRemoteHandshake({
+        compatibilityEpoch: RUNTIME_HOST_COMPATIBILITY_EPOCH - 1,
+      }),
+    },
+    {
+      surface: 'tui',
+      handshake: incompatibleRemoteHandshake({
+        protocolMin: RUNTIME_HOST_PROTOCOL_VERSION + 1,
+        protocolMax: RUNTIME_HOST_PROTOCOL_VERSION + 2,
+      }),
+    },
+    {
+      surface: 'run',
+      handshake: incompatibleRemoteHandshake({
+        compositionId: 'maka.other-composition',
+        compositionRevision: 'other-revision',
+      }),
+    },
+  ];
+
+  for (const { surface, handshake } of cases) {
+    const profile: RemoteRuntimeHostProfile = {
+      id: `office-${surface}-${handshake.compositionRevision}`,
+      name: 'Office',
+      kind: 'remote',
+      transport: { kind: 'tls', url: 'wss://runtime.example.com/runtime-host' },
+      rootId: 'c'.repeat(64),
+    };
+    await assert.rejects(
+      () =>
+        connectRuntimeHostCli(
+          { rootPath: '/unused-local-root', surface, profileId: profile.id },
+          {
+            connectRemoteProfile: (input) =>
+              connectRemoteRuntimeHostProfile(input, {
+                connect: async () => ({ kind: 'incompatible', handshake }),
+              }),
+            profileCatalog: singleRemoteProfileCatalog(profile),
+            loadClientInstanceId: async () => '33333333-3333-4333-8333-333333333333',
+          },
+        ),
+      (error: unknown) => {
+        assert.ok(error instanceof RuntimeHostRemoteCompatibilityError);
+        assert.equal(error.code, 'RUNTIME_HOST_REMOTE_INCOMPATIBLE');
+        assert.equal(
+          error.message,
+          new RuntimeHostRemoteCompatibilityError(profile.id, handshake).message,
+        );
+        assert.deepEqual(error.details, {
+          profileId: profile.id,
+          client: {
+            compatibilityEpoch: RUNTIME_HOST_COMPATIBILITY_EPOCH,
+            protocolMin: RUNTIME_HOST_PROTOCOL_VERSION,
+            protocolMax: RUNTIME_HOST_PROTOCOL_VERSION,
+            compositionId: INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID,
+          },
+          host: {
+            compatibilityEpoch: handshake.compatibilityEpoch,
+            protocolMin: handshake.protocolMin,
+            protocolMax: handshake.protocolMax,
+            compositionId: handshake.compositionId,
+            compositionRevision: handshake.compositionRevision,
+          },
+        });
+        return true;
+      },
+    );
+  }
+});
+
 function hostRegistration(
   overrides: Partial<{
     compatibilityEpoch: number;
@@ -334,3 +417,32 @@ function hostRegistration(
     ...overrides,
   };
 }
+
+function incompatibleRemoteHandshake(overrides: Partial<HostIncompatible> = {}): HostIncompatible {
+  return {
+    kind: 'incompatible',
+    hostEpoch: 'remote-host-epoch',
+    protocolMin: RUNTIME_HOST_PROTOCOL_VERSION,
+    protocolMax: RUNTIME_HOST_PROTOCOL_VERSION,
+    compatibilityEpoch: RUNTIME_HOST_COMPATIBILITY_EPOCH,
+    compositionId: INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID,
+    compositionRevision: 'remote-host-revision',
+    state: 'ready',
+    replacement: 'blocked_by_residency',
+    ...overrides,
+  };
+}
+
+function singleRemoteProfileCatalog(profile: RemoteRuntimeHostProfile): RuntimeHostProfileCatalog {
+  return {
+    read: async () => ({ schemaVersion: 1, profiles: [profile] }),
+    resolve: async (profileId) => {
+      assert.equal(profileId, profile.id);
+      return { profile, credential: 'opaque-token' };
+    },
+    create: async () => assert.fail('unexpected write'),
+    save: async () => assert.fail('unexpected write'),
+    remove: async () => assert.fail('unexpected write'),
+    removeIfCurrent: async () => assert.fail('unexpected write'),
+  };
+}